Skip Headers

Oracle® Database JPublisher User's Guide 10g Release 2 (10.2) Part Number B14188-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 6 Command-Line Options and Input Files

This chapter describes the usage and syntax details of JPublisher option settings and input files to specify program behavior. It is organized into the following sections:

- JPublisher Options

- JPublisher Input Files

## 6.1 JPublisher Options

The following sections list and discuss JPublisher command-line options:

- JPublisher Option Summary

- JPublisher Option Tips

- Notational Conventions

- Options for Input Files and Items to Publish

- Connection Options

- Options for Data Type Mappings

- Type Map Options

- Java Code-Generation Options

- PL/SQL Code Generation Options

- Input/Output Options

- Options to Facilitate Web Services Call-Outs

- Option to Access SQLJ Functionality

- Backward Compatibility Option

- Java Environment Options

- SQLJ Migration Options

### 6.1.1 JPublisher Option Summary

Table 6-1 summarizes JPublisher options. For default values, the abbreviation, NA, means not applicable. The Category column refers to the corresponding conceptual area, indicating the section of this chapter where the option is discussed.

Table 6-1 Summary of JPublisher Options

Option Name | Description | Default Value | Category
--- | --- | --- | ---
`-access` | Determines the access modifiers that JPublisher includes in generated method definitions. | `public` | Java code generation
`-adddefaulttypemap` | Appends an entry to the JPublisher default type map. | NA | Type maps
`-addtypemap` | Appends an entry to the JPublisher user type map. | NA | Type maps
`-builtintypes` | Specifies the data type mappings, `jdbc` or `oracle`, for built-in data types that are not numeric or large object (LOB). | `jdbc` | Data type mappings
`-case` | Specifies the case of Java identifiers that JPublisher generates. | `mixed` | Java code generation
`-classpath` | Adds to the Java classpath for JPublisher to resolve Java source and classes during translation and compilation. | Empty | Java environment
`-compatible` | Specifies a compatibility mode and modifies the behavior of `-usertypes=oracle`. See Also: "JPublisher Backward-Compatibility Modes and Settings" | `oradata` | Backward compatibility
`-compile` | Determines whether to proceed with Java compilation or suppress it. This option also affects SQLJ translation for backward-compatibility modes. | `true` | Input/output
`-compiler-executable` | Specifies a Java compiler version, in case you want a version other than the default. | NA | Java environment
`-context` | Specifies the class that JPublisher uses for SQLJ connection contexts. This can be the `DefaultContext` class, a user-specified class, or a JPublisher-generated inner class. | `DefaultContext` | Connection
`-defaulttypemap` | Sets the default type map that JPublisher uses. | Refer to "JPublisher User Type Map and Default Type Map". | Type maps
`-d` | Specifies the root directory for placement of compiled class files. | Empty (all files directly present in the current directory) | Input/output
`-dir` | Specifies the root directory for placement of generated source files. | Empty (all files directly present in the current directory) | Input/output
`-driver` | Specifies the driver class that JPublisher uses for Java Database Connectivity (JDBC) connections to the database. | `oracle.jdbc. OracleDriver` | Connection
`-encoding` | Specifies the Java encoding of JPublisher input and output files. | The value of the system property `file.encoding` | Input/output
`-endpoint` | Specifies a Web service endpoint. This option is used in conjunction with the `-proxywsdl` option. | NA | Web services
`-filtermodes` | Filters code generation according to specified parameter modes. | NA | Java code generation
`-filtertypes` | Filters code generation according to specified parameter types. | NA | Java code generation
`-generatebean` | Ensures that generated code conforms to the JavaBeans specification. | `false` | Java code generation
`-genpattern` | Defines naming patterns for generated code. | NA | Java code generation
`-gensubclass` | Specifies whether and how to generate stub code for user subclasses. | `true` | Java code generation
`-httpproxy` | Specifies a proxy URL to resolve the URL of a Web Services Description Language (WSDL) document for access through a firewall. This option is used in conjunction with the `-proxywsdl` option. | NA | Web services
`-input` or `-i` | Specifies a file that lists the types and packages that JPublisher translates. | NA | Input files/items
`-java` | Specifies server-side Java classes for which JPublisher generates client-side classes. | NA | Input files/items
`-lobtypes` | Specifies the `jdbc` or `oracle` data type mapping that JPublisher uses for `BLOB` and `CLOB` types. | `oracle` | Data type mappings
`-mapping` | Specifies the mapping that generated methods support for object attribute types and method argument types. Note: This option is deprecated in favor of the "`XXX` `types`" mapping options, but is supported for backward compatibility. | `objectjdbc` | Data type mappings
`-methods` | Determines whether JPublisher generates wrapper methods for stored procedures of translated SQL objects and PL/SQL packages. This option also determines whether JPublisher generates SQLJ classes or non-SQLJ classes, and whether it generates PL/SQL wrapper classes at all. There are settings to specify whether overloaded methods are allowed. | `all` | Java code generation
`-numbertypes` | Specifies the data type mappings, such as `jdbc`, `objectjdbc`, `bigdecimal`, or `oracle`, that JPublisher uses for numeric data types. | `objectjdbc` | Data type mappings
`-omit_schema_names` | Instructs JPublisher not to include the schema in SQL type name references in generated code. | Disabled (schema included in type names) | Java code generation
`-outarguments` | Specifies the holder type, such as arrays, Java API for XML-based Remote Procedure Call (JAX-RPC) holders, or function returns, for Java implementation of PL/SQL output parameters. | `array` | Java code generation
`-overwritedbtypes` | Specifies whether to ignore naming conflicts when creating SQL types. | `true` | PL/SQL code generation
`-package` | Specifies the name of the Java package into which JPublisher generates Java wrapper classes. | NA | Java code generation
`-plsqlfile` | Specifies a wrapper script to create and a dropper script to drop SQL conversion types for PL/SQL types and the PL/SQL package that JPublisher will use for generated PL/SQL code. | `plsql_wrapper.sql`, `plsql_dropper.sql` | PL/SQL code generation
`-plsqlmap` | Specifies whether to generate PL/SQL wrapper functions for stored procedures that use PL/SQL types. | `true` | PL/SQL code generation
`-plsqlpackage` | Specifies the PL/SQL package into which JPublisher generates PL/SQL code, such as call specifications, conversion functions, and wrapper functions. | `JPUB_PLSQL_WRAPPER` | PL/SQL code generation
`-props` or `-p` | Specifies a file that contains JPublisher options in addition to those listed on the command line. | NA | Input files/items
`-proxyclasses` | Specifies Java classes for which JPublisher generates wrapper classes and PL/SQL wrappers according to the `-proxyopts` setting. For Web services, you will typically use `-proxywsdl` instead, which uses `-proxyclasses` behind the scenes. | NA | Web services
`-proxyopts` | Specifies required layers of Java and PL/SQL wrappers and additional related settings. Is used as input for the `-proxywsdl` and `-proxyclasses` options. | `jaxrpc` | Web services
`-proxywsdl` | Specifies the URL of a WSDL document for which Web services client proxy classes and associated Java wrapper classes are generated along with PL/SQL wrappers. | NA | Web services
`-serializable` | Specifies whether the code generated for object types implements the `java.io.Serializable` interface. | `false` | Java code generation
`-sql` or `-s` | Specifies object types and packages, or subsets of packages, for which JPublisher generates Java classes, and optionally subclasses and interfaces. | NA | Input files/items
`-sqlj` | Specifies SQLJ option settings for the JPublisher invocation of the SQLJ translator. | NA | SQLJ
`-sqlstatement` | Specifies SQL queries or data manipulation language (DML) statements for which JPublisher generates Java classes, and optionally subclasses and interfaces, with appropriate methods. | NA | Input files/items
`-style` | Specifies the name of a "style file" for Java-to-Java type mappings. | NA | Data type mappings
`-sysuser` | Specifies the name and password for a superuser account that can be used to grant permissions to execute wrappers that access Web services client proxy classes in the database. | NA | Web services
`-tostring` | Specifies whether to generate a `toString()` method for object types. | `false` | Java code generation
`-typemap` | Specifies the JPublisher type map. | Empty | Type maps
`-types` | Specifies object types for which JPublisher generates code. Note: This option is deprecated in favor of `-sql`, but is supported for backward compatibility. | NA | Input files/items
`-url` | Specifies the URL that JPublisher uses to connect to the database. | `jdbc:oracle:oci:@` | Connection
`-user` or `-u` | Specifies an Oracle user name and password for connection. | NA | Connection
`-usertypes` | Specifies the `jdbc` or `oracle` type mapping that JPublisher uses for user-defined SQL types. | `oracle` | Data type mappings
`-vm` | Specifies a Java version, in case you want a version other than the default. | NA | Java environment

### 6.1.2 JPublisher Option Tips

Be aware of the following usage notes for JPublisher options:

- JPublisher always requires the `-user` option or its shorthand equivalent `-u`.

- Options are processed in the order in which they appear. Options from an `INPUT` file are processed at the point where the `-input` or `-i` option occurs. Similarly, options from a properties file are processed at the point where the `-props` or `-p` option occurs.

- As a rule, if a particular option appears more than once, JPublisher uses the value from the last occurrence. However, this is not true for the following options, which are cumulative:

  `-sql`

  `-types`, which is deprecated

  `-java`

  `-addtypemap` or `-adddefaulttypemap`

  `-style`

- In general, separate options and corresponding option values by an equal sign (`=`). However, when the following options appear on the command line, you can also use a space as a separator:

  `-sql` or `-s`, `-user` or `-u`, `-props` or `-p`, and `-input` or `-i`

- With the `-sqlj` option, you must use a space instead of an equal sign, because SQLJ settings following the `-sqlj` option use equal signs. Consider the following example, where each entry after "`-sqlj`" is a SQLJ option:

      % jpub -user=scott/tiger -sql=PERSON:Person -sqlj -optcols=true -optparams=true
             -optparamdefaults=datatype1(size1),datatype2(size)

- It is advisable to specify a Java package for generated classes with the `-package` option, either on the command line or in a properties file. For example, you could enter the following on the command line:

      % jpub -sql=Person -package=e.f ...

  Alternatively, you could enter the following in the properties file:

      jpub.sql=Person
      jpub.package=e.f
      ...

  These statements direct JPublisher to create the class `Person` in the Java package `e.f`, that is, to create the class `e.f.Person`.

  See Also: "Properties File Structure and Syntax"

- If you do not specify a type or package in the `INPUT` file or on the command line, then JPublisher translates all types and packages in the user schema according to the options specified on the command line or in the properties file.

### 6.1.3 Notational Con ventions

The JPublisher option syntax used in the following sections uses the following notational conventions:

- Braces `{...}` enclose a list of possible values. Specify only one of the values within the braces.

- A vertical bar `|` separates alternatives within braces.

- Terms in `italics` are for user input. Specify an actual value or string.

- Terms in boldface indicate default values.

- Square brackets `[...]` enclose optional items. In some cases, however, square brackets or parentheses are part of the syntax and must be entered verbatim. In this case, this manual uses boldface: `[`...`]` or `(`...`)`.

- Ellipsis points `...` immediately following an item, or items enclosed in brackets, mean that you can repeat the item any number of times.

- Punctuation symbols other than those described in this section are entered as shown in this manual. These include "`.`" and "`@`", for example.

### 6.1.4 Options for Input Files and Items to Publish

This section documents the following JPublisher options that specify key input, either JPublisher input files, such as `INPUT` files or properties files, or items to publish, such as SQL objects, PL/SQL packages, SQL queries, SQL DML statements, or server-side Java classes:

- Options for input files: `-input`, `-props`

- Options for items to publish: `-java`, `-sql`, `-sqlstatement`, `-types`

These options are discussed in alphabetic order.

#### 6.1.4.1 File Cont aining Names of Objects and Packages to Translate

The `-input` option specifies the name of a file from which JPublisher reads the names of SQL or PL/SQL entities or server-side Java classes to publish, along with any related information or instructions. JPublisher publishes each item in the list. You can think of the `INPUT` file as a makefile for type declarations, which lists the types that need Java class definitions.

The syntax of the `-input` option is as follows:

    -input=filename
    -i filename

Both formats are synonymous. The second one is a convenient command-line shortcut.

In some cases, JPublisher may find it necessary to translate some additional classes that do not appear in the `INPUT` file. This is because JPublisher analyzes the types in the `INPUT` file for dependencies before performing the translation and translates other types as necessary.

If you do not specify any items to publish in an `INPUT` file or on the command line, then JPublisher translates all user-defined SQL types and PL/SQL packages declared in the database schema to which it is connected.

See Also: "Translating Additional Types" and "INPUT File Structure and Syntax"

#### 6.1.4.2 Decla ration of Server-Side Java Classes to Publish

The `-java` option enables you to create client-side stub classes to access server-side classes. This is an improvement over earlier JPublisher releases in which calling Java stored procedures and functions from a database client required JDBC calls to associated PL/SQL wrappers.

The syntax of the `-java` option is as follows:

    -java=class_or_package_list

The functionality of the `-java` option mirrors that of the `-sql` option. It creates a client-side Java stub class to access a server-side Java class, in contrast to creating a client-side Java class to access a server-side SQL object or PL/SQL package.

When using the `-java` option, specify a comma-delimited list of server-side Java classes or packages.

Notes: To use the `-java` option, you must also specify the `-user` and `-url` settings for a database connection. Functionality of the `-java` option requires the `sqljutl.jar` library to be loaded in the database. For more information, refer to "Required Database Setup". It is advisable to use the same Java Development Kit (JDK) on the client as on the server.

For example:

    -java=foo.bar.Baz,foo.baz.*

Or, to specify the client-side class name corresponding to `Baz`, instead of using the server-side name by default:

    -java=foo.bar.Baz:MyBaz,foo.baz.*

This setting creates `MyBaz` and not `foo.bar.MyBaz`.

or:

    -java=foo.bar.Baz:foo.bar.MyBaz,foo.baz.*

You can also specify a schema:

    -java=foo.bar.Baz@SCOTT

If you specify the schema, then only that schema is searched. If you do not specify a schema, then the schema of the logged-in user, according to the `-user` option setting, is searched. This is the most likely scenario.

As an example, assume that you want to call the following method on the server:

    public String oracle.sqlj.checker.JdbcVersion.to_string();

Use the following `-java` setting:

    -java=oracle.sqlj.checker.JdbcVersion

Note: If JPublisher cannot find a specified class in the schema, a specified schema or the schema of the logged-in user, then it uses the `Class.forName()` method to search for the class among system classes in the Java virtual machine (JVM), typically Java run-time environment (JRE) or JDK classes.

Code Generation for -java Option When you use the `-java` option, generated code uses the following API:

    public class Client
    {
       public static String getSignature(Class[]);
       public static Object invoke(Connection, String, String,
                                   String, Object[]);
       public static Object invoke(Connection, String, String,
                                   Class[], Object[]);
    }

Classes for the API are located in the `oracle.jpub.reflect` package, so client applications must import this package.

For a setting of `-java=oracle.sqlj.checker.JdbcVersion`, JPublisher-generated code includes the following call:

    Connection conn = ...;
    String serverSqljVersion = (String)
               Client.invoke(conn, "oracle.sqlj.checker.JdbcVersion",
               "to_string", new Class[]{}, new Object[]{});

The `Class[]` array is for the method parameter types, and the `Object[]` array is for the parameter values. In this case, because `to_string` has no parameters, the arrays are empty.

Note the following:

- Any serializable type, such as `int[]` or `String[]`, can be passed as an argument.

- The semantics of this API are different from the semantics for invoking Java stored procedures or functions through a PL/SQL wrapper, in the following ways:

  - Arguments cannot be `OUT` or `IN OUT`. Returned values must be part of the function result.

  - Exceptions are properly returned.

  - Method invocation uses invoker's rights. There is no tuning to obtain definer's rights.

    See Also: Oracle Database Java Developer's Guide for information about invoker's rights and definer's rights

#### 6.1.4.3 Declaration of Server-Side Java Classes to Publish

The related options for publishing a server-side Java class are:

-     -dbajva=class_list

-     -proxyopts=single|multiple|static|arrayin|arrayout|arrayinout|arrayall|noload

-     -compatible=10.1

-     -sysuser=user/password

-     -plsqlfile=wrapper[,dropper]

-     -plsqlpackage=name

Oracle Database 10g release 1 (10.1) introduces the `-java` option to publish server-side Java classes. Oracle Database 10g release 2 (10.2) introduces a new approach toward server-side Java class publishing. The `-dbjava` option publishes a server-side Java class into PL/SQL, or into client-side Java class. The `class_list` specification is a comma-delimited list of server-side classes at the specified server. The `class_list` item is of the form `classname[:name[#interface]]`. It can also be a package name. Consider the option:

    -dbajva=classname[:name[#interface]]

If `name` is not specified, then the server-side Java class, `classname`, is published into PL/SQL, else into the client-side Java class, `name`. If `interface` is specified, then the interface file is generated for the client-side Java class.

When used with `-dbjava`, the `-proxyopts` option indicates whether to map instance methods using a singleton instance or using multiple instances, and also whether to map methods with array parameters assuming arrays as `IN`, `OUT`, `IN OUT`, or all the modes. The `-proxyopts=static` setting specifies that only static methods should be published. The default setting, `-proxyopts=single,arrayin`, indicates that instance methods are called using a singleton instance and array parameters are considered as input. The `-proxyopts=noload` setting forbids JPublisher from loading the generated PL/SQL and Java stored procedure wrappers.

The `-compatible=10.1` option makes `-dbjava` equivalent to `-java`.

#### 6.1.4.4 Declaration of Server-Side Java Classes to Publish

The related options for publishing server-side Java class are:

-     -proxyclasses=class_or_jar_list

-     -proxyopts=single|multiple|static|arrayin|arrayout|arrayinout|arrayall

-     -plsqlfile=wrapper[,dropper]

-     -plsqlpackage=name

The `-proxyclasses` option is similar to `-dbjava`. While `-dbjava` requires that the classes to be published exist in the database, `-proxyclasses` requires that the classes appear in the classpath. Typically, by using `-proxyclasses`, you can load the exposed classes and the generated wrappers into the database later.

The `-proxyclasses` option generates only a PL/SQL wrapper. Unlike `-dbjava`, it will not generate client-side Java code for a server-side Java class. Also, unlike `-dbjava`, `-proxyclasses` does not load the generated Java stored procedure into the database.

You can use the `-proxyclasses` option to specify a comma-delimited list of Java classes, either loose classes or Java Archive (JAR) files, for which JPublisher creates PL/SQL wrappers. Depending on the situation, JPublisher can also create Java wrapper classes to afford access from PL/SQL. Each of the classes processed must have either public, static methods or, for classes in which you want to publish instance methods, a `public` zero-argument constructor.

To summarize, the following are generated for each class being processed, depending on the `-proxyopts` option settings:

- A PL/SQL wrapper to allow access from PL/SQL. This is always generated.

- A wrapper class to expose Java instance methods as static methods, if there are any instance methods to publish.

Instance methods must be exposed as static methods to allow access from PL/SQL. A wrapper class is also necessary if the wrapped class uses anything other than Java primitive types in the method calling sequences.

While using the `-proxyclasses` option directly, you can specify JAR files and Java classes that exist in the classpath. Classes and JAR files can be specified as follows:

- Class name, such as `foo.bar.Baz` or `foo.bar.Baz.class`

- Package name, such as `foo.bar.*`, for `@``server` mode only

- JAR or ZIP file name, such as `foo/bar/baz.jar` or `Baz.zip`

- JAR or ZIP file name followed by parenthesized list of classes or packages, such as `baz.jar (foo.MyClass1, foo.bar.MyClass2, foo1.*)`

#### 6.1.4.5 Settings for Java and PL/SQL Wrapper Generation

The `-proxyopts` option is used as input by the `-dbjava`, `-proxywsdl`, and `-proxyclasses` options and specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers for server-side Java classes.

The syntax of the `-proxyopts` option is as follows:

    -proxyopts=setting1,setting2,...

This option uses the basic settings, which can be used individually or in combinations. In this discussion, processed classes are the classes that are wrapped by using the `-dbjava`, `-proxywsdl`, or `-proxyclasses` options.

Where Java wrapper classes are generated, the wrapper class for a class `foo.bar.MyClass` would be `foo.bar.MyClassJPub`, unless the package is overridden by a setting of the `-package` option.

You can use the basic `-proxyopts` settings as follows:

- Use the `static` setting to specify the treatment of static methods of processed classes.

  With this setting, in the PL/SQL wrapper, a wrapper procedure is generated for each static method. Without this setting, static methods are ignored. For classes with only static methods, wrapper classes are not required for processed classes that use only Java primitive types in their method calling sequences.

- Use the `multiple` or `single` setting to specify treatment of instance methods of processed classes, where you want instance methods exposed as static methods. In either case, for each processed class, JPublisher generates an intermediate Java class that wraps instance methods with static methods, in addition to generating a PL/SQL wrapper.

  Use the `instance` setting to specify treatment of instance methods of processed classes, where you want instance methods maintained as instance methods.

  These settings function as follows:

  - `multiple`

    For each processed class, the Java wrapper class has a static equivalent for each instance method through the use of handles, which identify instances of wrapped classes.

  - `single`

    Only a single default instance of each wrapped class is used during run time. For each processed class, the Java wrapper class has static wrapper methods for instance methods without requiring the use of handles. This is the singleton mechanism.

  - `instance`

    Instance methods are wrapped as instance methods in the Java wrapper class.

    Note: The `instance` setting is not appropriate for Web services.

  The instance methods are ignored if one of these settings or a `jaxrpc` or `soap` setting, which implies `single`, is not specified. For either of these settings, only classes that provide a public zero-argument constructor are processed. You can use both settings to generate wrapper classes of both styles.

- Use the `jaxrpc` or `soap` setting to publish instance methods of Web services client proxy classes. These settings function as follows:

  - `jaxrpc`

    This is the default setting. It is a convenient setting for wrapping JAX-RPC client proxy classes, which is appropriate for use with Oracle Application Server 10g 10.0.1 and later releases. JPublisher creates a Java wrapper class for each processed class and also creates the PL/SQL wrapper. Client proxy classes do not have static methods to be published, and instance methods are published using the singleton mechanism by default. Therefore, when processing JAX-RPC client proxy classes, `-proxyopts=jaxrpc` implies `-proxyopts=single`. The `jaxrpc` setting also results in generation of special code that is specific to JAX-RPC clients.

  - `soap`

    This setting is equivalent to the `jaxrpc` setting, but is used for wrapping SOAP client proxy classes instead of JAX-RPC client proxy classes. This is appropriate for use with Oracle Application Server 10g 9.0.4 and earlier releases.

Here are some basic uses of the `-proxyopts` option:

    -proxyopts=jaxrpc

    -proxyopts=soap

    -proxyopts=static

    -proxyopts=static,instance

    -proxyopts=single

    -proxyopts=single,multiple

    -proxyopts=static,multiple

The `static,instance` setting publishes static and instance methods. The `single,multiple` setting publishes only instance methods, using both the singleton mechanism and the handle mechanism. The `static,multiple` setting publishes static and instance methods, using the handle mechanism to expose instance methods as static methods.

Note: It is typical to explicitly use the `-proxyopts` option with the `-proxyclasses` option than with the `-proxywsdl` option. For the use of `-proxywsdl` with 10.0.x releases of Oracle Application Server 10g, the default `-proxyopts=jaxrpc` setting is sufficient.

There are additional, advanced `-proxyopts` settings as well. The functionality of each setting is as follows:

- `noload`

  Use this to indicate that the generated code need not be loaded into the database. By default, the generated code is loaded.

- `recursive`

  Use this to indicate that when processing a class that extends another class, also create PL/SQL and Java wrappers, if appropriate, for inherited methods.

- `tabfun`

  Use this with the `jaxrpc` or `soap` setting for JPublisher to generate PL/SQL table functions for the PL/SQL package for each of the wrapped Web services operations. This exposes data through database tables rather than stored procedures or functions.

- `deterministic`

  Use this to indicate in the generated PL/SQL wrapper that the wrapped methods are deterministic. This would typically be used with the `tabfun` setting. Deterministic is a PL/SQL annotation.

  See Also: Oracle Database SQL Reference for information about `DETERMINISTIC` functions

- `main(0,...)`

  Use this with the `static` setting to define the wrapper methods to be generated if there is a `public void String main(String[])` method in the class. A separate method is generated for each number of arguments that you want to support. You can use commas or hyphens when indicating the number of arguments, as in the following examples:

  - `main` or `main(0)` produces a wrapper method only for zero arguments.

  - `main(0,1)` produces wrapper methods for zero arguments and one argument. This is the default setting.

  - `main(0-3)` produces wrapper methods for zero, one, two, and three arguments.

  - `main(0,2-4)` produces wrapper methods for zero, two, three, and four arguments.

  The maximum number of arguments in the wrapper method for the `main()` method is according to PL/SQL limitations.

The following example uses the `jaxrpc` basic setting by default. It also uses table functions and indicates that wrapped methods are deterministic:

    -proxyopts=tabfun,deterministic

The following example explicitly sets the `static` mode, processing classes that are not client proxy classes, and specifies that the generated code should not be loaded into the database:

    -proxyopts=static,noload

#### 6.1.4.6 Input Pro perties File

The `-props` option specifies the name of a JPublisher properties file that specifies JPublisher option settings. JPublisher processes the properties file as if its contents were inserted in sequence on the command line where the `-props` option is specified.

The syntax of the `-props` option is as follows:

    -props=filename
    -p filename

Both formats are synonymous. The second one is provided as a convenient command-line shortcut.

If more than one properties file appears on the command line, then JPublisher processes them with the other command-line options, in the order in which they appear.

See Also: "Properties File Structure and Syntax"

Note: Encoding settings, either set through the JPublisher `-encoding` option or the Java `file.encoding` setting, do not apply to Java properties files. Properties files always use the `8859_1` encoding. This is a feature of Java in general, and not of JPublisher in particular. However, you can use Unicode escape sequences in a properties file.

#### 6.1.4.7 Dec laration of Object Types and Packages to Translate

The `-sql` option is used to specify the user-defined SQL types, such as objects or collections, or the PL/SQL packages that need to be published. Optionally, you can specify the user subclasses or interfaces that should be generated. You can publish all or a specific subset of a PL/SQL package.

The syntax of the `-sql` option is as follows:

    -sql={toplevel|object_type_and_package_translation_syntax}
    -s {toplevel|object_type_and_package_translation_syntax}

The two formats of this option, `-sql` and `-s`, are synonymous. The `-s` format is provided as a convenient command-line shortcut.

You can use the `-sql` option when you do not need the generality of an `INPUT` file. The `-sql` option lets you list one or more database entities declared in SQL that you want JPublisher to translate. Alternatively, you can use several `-sql` options in the same command line, or several `jpub.sql` options in a properties file.

You can mix user-defined type names and package names in the same `-sql` declaration. JPublisher can detect whether each item is an object type or a package. You can also use the `-sql` option with the keyword `toplevel` to translate all top-level PL/SQL subprograms in a schema. The `toplevel` keyword is not case-sensitive.

If you do not specify any types or packages to translate in the `INPUT` file or on the command line, then JPublisher translates all the types and packages in the schema to which you are connected. In this section, the `-sql` option is explained in terms of the equivalent `INPUT` file syntax.

See Also: "Understanding the Translation Statement"

You can use the any of the following syntax modes:

- `-sql=``name_a`

  JPublisher publishes `name_a`, naming the generated class according to the default settings. In an `INPUT` file, you specify this options as follows:

      SQL name_a

- `-sql=``name_a:class_c`

  JPublisher publishes `name_a` as the generated Java class `class_c`. In an `INPUT` file, you specify this options as follows:

      SQL name_a AS class_c

- `-sql=``name_a``:``class_b``:``class_c`

  In this case, `name_a` must represent an object type. JPublisher generates the Java class, `class_b`, and a stub class, `class_c`, that extends `class_b`. You provide the code for `class_c`, which is used to represent `name_a` in your Java code. In an `INPUT` file, you specify this options as follows:

      SQL name_a GENERATE class_b AS class_c

- `-sql=``name_a``:``class_b``#``intfc_b`

- `-sql=``name_a``:``class_b``:``class_c``#``intfc_c`

  You can use either of these syntax formats to have JPublisher generate a Java interface. This feature is particularly useful for Web services. In the first case, `class_b` represents `name_a` and implements `intfc_b`. In the second case, `class_c` represents `name_a`, extends `class_b`, and implements `intfc_c`.

  See Also: "Generation of Java Interfaces"

  Specify an interface for either the generated class or the user subclass, but not both. In an `INPUT` file, this syntax is as follows:

      SQL name_a
          [GENERATE  class_b
                     [ implements intfc_b] ]
          [AS        class_c
                     [ implements intfc_c ] ]
          ...

Notes: Only SQL names that are not case-sensitive are supported on the JPublisher command line. If a user-defined type was defined in a case-sensitive way in SQL, using quotes, then you must specify the name in the JPublisher `INPUT` file instead of specifying the user-defined type, in quotes, on the command line. If your desired class and interface names follow a pattern, you can use the `-genpattern` command-line option for convenience.

If you enter more than one item for translation, then the items must be separated by commas, without any white space. This example assumes that `CORPORATION` is a package and that `EMPLOYEE` and `ADDRESS` are object types:

    -sql=CORPORATION,EMPLOYEE:OracleEmployee,ADDRESS:JAddress:MyAddress

JPublisher interprets this command as follows:

    SQL CORPORATION
    SQL EMPLOYEE AS OracleEmployee
    SQL ADDRESS GENERATE JAddress AS MyAddress

JPublisher performs the following actions:

- Creates a wrapper class for the `CORPORATION` package.

- Translates the `EMPLOYEE` object type as `OracleEmployee`.

- Generates an object reference class, `OracleEmployeeRef`.

- Translates `ADDRESS` as `JAddress`, but generates code and references so that `ADDRESS` objects will be represented by the `MyAddress` class.

- Generates a `MyAddress` stub, which extends `JAddress`, where you can write your custom code.

- Generates an object reference class `MyAddressRef`.

If you want JPublisher to translate all the top-level PL/SQL subprograms in the schema to which JPublisher is connected, then enter the keyword `toplevel` following the `-sql` option. JPublisher treats the top-level PL/SQL subprograms as if they were in a package. For example:

    -sql=toplevel

JPublisher generates a wrapper class, `toplevel`, for the top-level subprograms. If you want the class to be generated with a different name, you can declare the name as follows:

    -sql=toplevel:MyClass

Note that this is synonymous with the following `INPUT` file syntax:

    SQL toplevel AS MyClass

Similarly, if you want JPublisher to translate all the top-level PL/SQL subprograms in some other schema, then enter:

    -sql=schema_name.toplevel

In this example, `schema_name` is the name of the schema containing the top-level subprograms. In addition, there are features to publish only a subset of stored procedures in a PL/SQL package or at the top level, using the following syntax:

    -sql=plsql_package(proc1+proc2+proc3+...)

Use a plus sign (`+`) between stored procedure names. Alternatively, for the SQL top level, use:

    -sql=toplevel(proc1+proc2+proc3+...)

The following syntax is for a JPublisher `INPUT` file, where commas are used between stored procedure names:

    SQL plsql_package (proc1, proc2, proc3, ...) AS ...

Notes: In an `INPUT` file, put a stored procedure name in quotes if it is case-sensitive. For example, "`proc1`". JPublisher assumes that names that are not in quotes are not case-sensitive. Case-sensitive names are not supported on the JPublisher command line. Specified stored procedure names can end in the wildcard character, "`%`". The specification "`myfunc%`", for example, matches all stored procedures that have their name starting with `myfunc`, such as `myfunc1`.

You can also specify the subset according to stored procedure names and argument types by using the following syntax:

    myfunc(sqltype1, sqltype2, ...)

In this case, only those stored procedures that match in name and the number and types of arguments will be published. For example:

    -sql=mypackage(myfunc1(NUMBER, CHAR)+myfunc2(VARCHAR2))

#### 6.1.4.8 Declar ation of SQL Statements to Translate

The `-sqlstatement` option enables you to publish `SELECT`, `INSERT`, `UPDATE`, or `DELETE` statements as Java methods. JPublisher generates SQLJ classes for this functionality.

The syntax of the `-sqlstatement` option is as follows:

    -sqlstatement.class=ClassName:UserClassName#UserInterfaceName
    -sqlstatement.methodName=sqlStatement
    -sqlstatement.return={both|resultset|beans}

Use `-sqlstatement.class` to specify the Java class in which the method will be published. In addition to the JPublisher-generated class, you can optionally specify a user subclass of the generated class, a user interface for the generated class or subclass, or both. Functionality for subclasses and interfaces is the same as for the `-sql` option. If you also use the JPublisher `-package` option, then the class you specify will be in the specified package. The default class is `SQLStatements`.

Use `-sqlstatement.``methodName` to specify the desired Java method name and the SQL statement. For a `SELECT` statement, use `-sqlstatement.return` to specify whether JPublisher should generate a method that returns a generic `java.sql.ResultSet` instance, a method that returns an array of JavaBeans, or both. Generic implies that the column types of the result set are unknown or unspecified.

For queries, however, the column types are actually known. This provides the option of returning specific results through an array of beans. The name of the method returning `ResultSet` will be `methodName``()`. The name of the method returning JavaBeans will be `methodName` `Beans()`.

Note: If your desired class and interface names follow a pattern, then you can use the `-genpattern` option for convenience.

JPublisher `INPUT` file syntax is as follows:

    SQLSTATEMENTS_TYPE ClassName AS UserClassName
                                 IMPLEMENTS UserInterfaceName
    SQLSTATEMENTS_METHOD aSqlStatement AS methodName

Here is a set of sample settings:

    -sqlstatement.class=MySqlStatements
    -sqlstatement.getEmp="select ename from emp
                          where ename=:{myname VARCHAR}"
    -sqlstatement.return=both

These settings result in the generated code shown in "Generated Code: SQL Statement".

In addition, be aware that a style file specified through the `-style` option is relevant to the `-sqlstatement` option. If a SQL statement uses an Oracle data type `X`, which corresponds to a Java type `Y`, and type `Y` is mapped to a Java type `Z` in the style file, then methods generated as a result of the `-sqlstatement` option will use `Z`, and not `Y`.

For `SELECT` or DML statement results, you can use a style file to map the results to `javax.xml.transform.Source`, `oracle.jdbc.rowset.OracleWebRowSet`, or `org.w3c.dom.Document`.

See Also: "JPublisher Styles and Style Files" and "REF CURSOR Types and Result Sets Mapping"

Example: Using an XML Type This example shows the use of an XML type, `SYS.XMLTYPE`, with the `-sqlstatement` option. Assume the following table is created using SQL*Plus:

    SQL>  CREATE TABLE xmltab (a XMLTYPE);

Now, assume the following JPublisher command to publish an `INSERT` statement:

    % jpub  -u scott/tiger -style=webservices10
            -sqlstatement.addEle="insert into xmltab values(:{a sys.xmltype})"

This command causes the generation of the following methods:

    public int addEle(javax.xml.transform.Source a) throws java.rmi.RemoteException;
    public int addEleiS(javax.xml.transform.Source[] a)
                                            throws java.rmi.RemoteException;

This is because `SYS.XMLTYPE` is mapped to `oracle.sql.SimpleXMLType`, which the `webservices10` style file further maps to `javax.xml.transform.Source`.

The method name, `addEleiS`, is used to avoid method overloading according to JPublisher naming conventions, with `i` reflecting the `int` return type and `S` reflecting the `Source` parameter type.

Note: This example assumes that JDK 1.4 is installed and used by JPublisher. If it is installed but not used by default, then you can set the `-vm` and `-compiler-executable` options to specify a JDK 1.4 JVM and compiler. For more information, refer to"Java Environment Options".

#### 6.1.4.9 Decla ration of Object Types to Translate

The `-types` option lets you list one or more individual object types that you want JPublisher to translate. The syntax of the `-types` option is as follows:

    -types=type_translation_syntax

Note: The `-types` option is currently supported for compatibility, but it is deprecated. Use the `-sql` option instead.

You can use the `-types` option, for SQL object types only and when you do not need the generality of an `INPUT` file. Except for the fact that the `-types` option does not support PL/SQL packages, it is identical to the `-sql` option.

If you do not enter any types or packages to translate in the `INPUT` file or on the command line, then JPublisher translates all the types and packages in the schema to which you are connected. The command-line syntax lets you indicate three possible type translations.

- `-types=``name_a`

  JPublisher interprets this syntax as:

      TYPE name_a

- `-types=``name_a``:``name_b`

  JPublisher interprets this syntax as:

      TYPE name_a AS name_b

- `-types=``name_a``:``name_b``:``name_c`

  JPublisher interprets this syntax as:

      TYPE name_a GENERATE name_b AS name_c

`TYPE`, `TYPE...AS`, and `TYPE...GENERATE...AS` commands have the same functionality as `SQL`, `SQL...AS`, and `SQL...GENERATE...AS` syntax.

See Also: "Understanding the Translation Statement"

Enter `-types=...` on the command line, followed by one or more object type translations that you want JPublisher to perform. If you enter more than one item, then the items must be separated by commas without any white space. For example, if you enter:

    -types=CORPORATION,EMPLOYEE:OracleEmployee,ADDRESS:JAddress:MyAddress

JPublisher interprets this command as:

    TYPE CORPORATION
    TYPE EMPLOYEE AS OracleEmployee
    TYPE ADDRESS GENERATE JAddress AS MyAddress

### 6.1.5 Connection Options

This section documents options related to the database connection that JPublisher uses. The options are discussed in the alphabetic order.

#### 6.1.5.1 SQLJ Con nection Context Classes

The `-context` option specifies the connection context class that JPublisher uses, and possibly declares, for SQLJ classes that JPublisher produces. The syntax of the `-context` option is as follows:

    -context={generated|DefaultContext|user_defined}

The `-context=DefaultContext` setting is the default and results in any JPublisher-generated SQLJ classes using the SQLJ default connection context class, `sqlj.runtime.ref.DefaultContext`, for all connection contexts. This is sufficient for most uses.

Alternatively, you can specify any user-defined class that implements the standard `sqlj.runtime.ConnectionContext` interface and exists in the classpath. The specified class will be used for all connection contexts.

Note: With a user-defined class, instances of that class must be used for output from the `getConnectionContext()` method or for input to the `setConnectionContext()` method. Refer to "Connection Contexts and Instances in SQLJ Classes", for information about these methods.

The `-context=generated` setting results in an inner class declaration for the `_Ctx` connection context class in all SQLJ classes generated by JPublisher. So, each class uses its own SQLJ connection context class. This setting may be appropriate for Oracle8i compatibility mode, but it is otherwise not recommended. Using the `DefaultContext` class or a user-defined class avoids the generation of additional connection context classes. You can specify the `-context` option on the command line or in a properties file.

Notes for -context Usage in Backward-Compatibility Modes

If you use a backward-compatibility mode and use `.sqlj` files and the SQLJ translator directly, then a `-context=DefaultContext` setting gives you greater flexibility if you translate and compile your `.sqlj` files in separate steps, translating with the SQLJ `-compile=false` setting. If you are not using JDK 1.2-specific types, such as `java.sql.BLOB`, `CLOB`, `Struct`, `Ref`, or `Array`, then you can compile the resulting `.java` files under JDK 1.1, JDK 1.2, or later. This is not the case with the `-context=generated` setting, because SQLJ connection context classes in JDK 1.1 use `java.util.Dictionary` instances for object type maps, while SQLJ connection context classes in JDK 1.2 or later use `java.util.Map` instances.

A benefit of using the `-context=generated` setting, if you are directly manipulating `.sqlj` files, is that it permits full control over the way the SQLJ translator performs online checking. Specifically, you can check SQL user-defined types and PL/SQL packages against an appropriate exemplar database schema. However, because JPublisher generates `.sqlj` files from an existing schema, the generated code is already verified as correct through construction from that schema.

#### 6.1.5.2 The Default datasource Option

You can use `-datasource` to specify the default data source for publishing SQL, PL/SQL, AQ, and server-side Java classes. With `-datasource` set, if the JDBC connection is not explicitly set by the application at run time, then the generated code will look up the specified Java Naming and Directory Interface (JNDI) location to get the data source and further get the JDBC connection from that data source.

The syntax of the `-datasource` option is as follows:

    -datasource=jndi_location

#### 6.1.5.3 JDBC Driver Class for Database Connection

The `-driver` option specifies the driver class that JPublisher uses for JDBC connections to the database. The syntax of this option is as follows:

    -driver=driver_class_name

The default setting is:

    -driver=oracle.jdbc.OracleDriver

This setting is appropriate for any Oracle JDBC driver.

#### 6.1.5.4 Connection URL for Target Database

You can use the `-url` option to specify the URL of the database to which you want to connect. The syntax of the `-url` option is as follows:

    -url=URL

The default setting is:

    -url=jdbc:oracle:oci:@

To specify the JDBC Thin driver, use a setting of the following form:

    -url=jdbc:oracle:thin:@host:port/servicename

In this syntax, `host` is the name of the host on which the database is running, `port` is the port number, and `servicename` is the name of the database service.

Note: The use of system identifiers (SIDs) is deprecated in Oracle Database 10g, but it is still supported for backward compatibility. Their use is of the form `host``:``port``:``sid`. For the Oracle JDBC Oracle Call Interface (OCI) driver, use `oci` in the connect string in any new code. For backward compatibility, however, `oci8` is still accepted for Oracle8i drivers.

#### 6.1.5.5 User Na me and Password for Database Connection

JPublisher requires the `-user` option, which specifies an Oracle user name and password, so that it can connect to the database. If you do not enter the `-user` option, then JPublisher prints an error message and stops execution.

The syntax of the `-user` option is as follows:

    -user=username/password
    -u username/password

Both formats are equivalent. The second one is provided as a convenient command-line shortcut.

For example, the following command directs JPublisher to connect to the database with the user name `scott` and password `tiger`:

    % jpub -user=scott/tiger -input=demoin -dir=demo -mapping=oracle -package=corp

### 6.1.6 Optio ns for Data Type Mappings

The following options control the data type mappings that JPublisher uses to translate object types, collection types, object reference types, and PL/SQL packages to Java classes:

- The `-usertypes` option controls JPublisher behavior for user-defined types, in conjunction with the `-compatible` option for `oracle` mapping. Specifically, it controls whether JPublisher implements the Oracle `ORAData` interface or the standard `SQLData` interface in generated classes, and whether JPublisher generates code for collection and object reference types.

- The `-numbertypes` option controls data type mappings for numeric types.

- The `-lobtypes` option controls data type mappings for the `BLOB`, `CLOB`, and `BFILE` types.

- The `-builtintypes` option controls data type mappings for non-numeric, non-LOB, and predefined SQL and PL/SQL types.

These four options are known as the type-mapping options.

For an object type, JPublisher applies the mappings specified by the type-mapping options to the object attributes and the arguments and results of any methods included with the object. The mappings control the types that the generated accessor methods support. For example, they support the types the `get` `XXX``()` methods return and the `set` `XXX``()` methods take.

For a PL/SQL package, JPublisher applies the mappings to the arguments and results of the methods in the package. For a collection type, JPublisher applies the mappings to the element type of the collection.

In addition, there is a subsection here for the `-style` option, which you can use to specify Java-to-Java type mappings, typically to support Web services. This involves an extra JPublisher step. A SQL type is mapped to a Java type that is not supported by Web services, in the JPublisher-generated base class. Then this Java type is mapped to a Java type that is supported by Web services, in the JPublisher-generated user subclass.

See Also: "JPublisher Styles and Style Files"

#### 6.1.6.1 Map pings for Built-In Types

The `-builtintypes` option controls data type mappings for all the built-in data types except the LOB types, which are controlled by the `-lobtypes` option, and the different numeric types, which are controlled by the `-numbertypes` option. The syntax of the `-builtintypes` option is as follows:

    -builtintypes={jdbc|oracle}

Table 6-2 lists the data types affected by the `-builtintypes` option and shows their Java type mappings for `-builtintypes=oracle` and `-builtintypes=jdbc`, which is the default.

Table 6-2 Mappings for Types Affected by the -builtintypes Option

SQL Data Type | Oracle Mapping Type | JDBC Mapping Type
--- | --- | ---
`CHAR`, `CHARACTER`, `LONG`, `STRING`, `VARCHAR`, `VARCHAR2` | `oracle.sql.CHAR` | `java.lang.String`
`RAW`, `LONG RAW` | `oracle.sql.RAW` | `byte[]`
`DATE` | `oracle.sql.DATE` | `java.sql.Timestamp`
`TIMESTAMP` `TIMESTAMP WITH TZ` `TIMESTAMP WITH LOCAL TZ` | `oracle.sql.TIMESTAMP` `oracle.sql.TIMESTAMPTZ` `oracle.sql.TIMESTAMPLTZ` | `java.sql.Timestamp`

#### 6.1.6.2 Map pings for LOB Types

The `-lobtypes` option controls data type mappings for LOB types. The syntax of the `-lobtypes` option is as follows:

    -lobtypes={jdbc|oracle}

Table 6-3 shows how these types are mapped for `-lobtypes=oracle`, which is the default, and for `-lobtypes=jdbc`.

Table 6-3 Mappings for Types Affected by the -lobtypes Option

SQL Data Type | Oracle Mapping Type | JDBC Mapping Type
--- | --- | ---
`CLOB` | `oracle.sql.CLOB` | `java.sql.Clob`
`BLOB` | `oracle.sql.BLOB` | `java.sql.Blob`
`BFILE` | `oracle.sql.BFILE` | `oracle.sql.BFILE`

Notes: `BFILE` is an Oracle-specific SQL type, so there is no standard `java.sql.Bfile` Java type. `NCLOB` is an Oracle-specific SQL type. It denotes an `NCHAR` form of use of a `CLOB` and is represented as an instance of `oracle.sql.NCLOB` in Java. The `java.sql.Clob` and `java.sql.Blob` interfaces were introduced in the JDK 1.2 versions.

#### 6.1.6.3 Map pings for Numeric Types

The `-numbertypes` option controls data type mappings for numeric SQL and PL/SQL types. The syntax of the `-numbertypes` option is as follows:

    -numbertypes={jdbc|objectjdbc|bigdecimal|oracle}

The following choices are available:

- In JDBC mapping, most numeric data types are mapped to Java primitive types, such as `int` and `float`, and `DECIMAL` and `NUMBER` are mapped to `java.math.BigDecimal`.

- In Object JDBC mapping, which is the default, most numeric data types are mapped to Java wrapper classes, such as `java.lang.Integer` and `java.lang.Float`. `DECIMAL` and `NUMBER` are mapped to `java.math.BigDecimal`.

- In `BigDecimal` mapping, all numeric data types are mapped to `java.math.BigDecimal`.

- In Oracle mapping, all numeric data types are mapped to `oracle.sql.NUMBER`.

Table 6-4 lists the data types affected by the `-numbertypes` option and shows their Java type mappings for `-numbertypes=jdbc` and `-numbertypes=objectjdbc`, which is the default.

Table 6-4 Mappings for Types Affe cted by the -numbertypes Option

SQL Data Type | JDBC Mapping Type | Object JDBC Mapping Type
--- | --- | ---
`BINARY_INTEGER`, `INT`, `INTEGER`, `NATURAL`, `NATURALN`, `PLS_INTEGER`, `POSITIVE`, `POSITIVEN`, `SIGNTYPE` | `int` | `java.lang.Integer`
`SMALLINT` | `int` | `java.lang.Integer`
`REAL` | `float` | `java.lang.Float`
`DOUBLE PRECISION`, `FLOAT` | `double` | `java.lang.Double`
`DEC`, `DECIMAL`, `NUMBER`, `NUMERIC` | `java.math.BigDecimal` | `java.math.BigDecimal`

#### 6.1.6.4 Map pings for User-Defined Types

The `-usertypes` option controls whether JPublisher implements the Oracle `ORAData` interface or the standard `SQLData` interface in generated classes for user-defined types. The syntax of the `-usertypes` option is as follows:

    -usertypes={oracle|jdbc}

When `-usertypes=oracle`, which is the default, JPublisher generates `ORAData` classes for object, collection, and object reference types.

When `-usertypes=jdbc`, JPublisher generates `SQLData` classes for object types. JPublisher does not generate classes for collection or object reference types in this case. You must use `java.sql.Array` for all collection types and `java.sql.Ref` for all object reference types.

Notes: The `-usertypes=jdbc` setting requires JDK 1.2 or later, because the `SQLData` interface is a JDBC 2.0 feature. With certain settings of the `-compatible` option, a `-usertypes=oracle` setting results in classes that implement the deprecated `CustomDatum` interface instead of `ORAData`.

#### 6.1.6.5 Map pings for All Types

The `-mapping` option specifies mapping for all data types, so offers little flexibility between types. The syntax of the `-mapping` option is as follows:

    -mapping={jdbc|objectjdbc|bigdecimal|oracle}

Note: This option is deprecated in favor of the more specific type mapping options: `-usertypes`, `-numbertypes`, `-builtintypes`, and `-lobtypes`. However, it is still supported for backward compatibility.

The `-mapping=oracle` setting is equivalent to setting all the type mapping options to `oracle`. The other `-mapping` settings are equivalent to setting `-numbertypes` equal to the value of `-mapping` and setting the other type mapping options to their defaults. This is summarized in Table 6-5.

Table 6-5 Relation of -mapping Settings to Other Mapping Option Settings

-mapping Setting | -builtintypes= | -numbertypes= | -lobtypes= | -usertypes=
--- | --- | --- | --- | ---
`-mapping=oracle` | `oracle` | `oracle` | `oracle` | `oracle`
`-mapping=jdbc` | `jdbc` | `jdbc` | `oracle` | `oracle`
`-mapping=objectjdbc` (default) | `jdbc` | `objectjdbc` | `oracle` | `oracle`
`-mapping=bigdecimal` | `jdbc` | `bigdecimal` | `oracle` | `oracle`

Note: Options are processed in the order in which they appear on the command line. Therefore, if the `-mapping` option precedes one of the specific type mapping options, `-builtintypes`, `-lobtypes`, `-numbertypes`, or `-usertypes`, then the specific type mapping option overrides the `-mapping` option for the relevant types. If the `-mapping` option follows one of the specific type mapping options, then the specific type mapping option is ignored.

#### 6.1.6.6 Sty le File for Java-to-Java Type Mappings

JPublisher style files allow you to specify Java-to-Java type mappings. One use for this is to ensure that generated classes can be used in Web services. You use the `-style` option to specify the name of a style file. You can use the `-style` option multiple times. The settings accumulate in order. The syntax of the `-style` option is as follows:

    -style=stylename

Typically, Oracle supplies the style files, but there may be situations in which you would edit or create your own. To use the Oracle style file for Web services in Oracle Database 10g, for example, use the following setting:

    -style=webservices10

See Also: "JPublisher Styles and Style Files"

### 6.1.7 Type Map Optio ns

JPublisher code generation is influenced by entries in the JPublisher user type map or default type map, primarily to make signatures with PL/SQL types accessible to JDBC. A type map entry has one of the following formats:

    -type_map_option=opaque_sql_type:java_type
    -type_map_option=numeric_indexed_by_table:java_numeric_type[max_length]
    -type_map_option=char_indexed_by_table:java_char_type[max_length](elem_size)
    -type_map_option=plsql_type:java_type:sql_type:sql_to_plsql_func:plsql_to_sql_func

In the type map syntax, `sql_to_plsql_func` and `plsql_to_sql_func` are for functions that convert between SQL and PL/SQL. Note that `[`...`]` and `(`...`)` are part of the syntax. Also note that some operating systems require you to quote command-line options that contain special characters.

The related options, which are discussed in alphabetic order in the following sections, are `-addtypemap`, `-adddefaulttypemap`, `-defaulttypemap`, and `-typemap`. The difference between `-addtypemap` and `-typemap` is that `-addtypemap` appends entries to the user type map, while `-typemap` replaces the existing user type map with the specified entries. Similarly, `-adddefaulttypemap` appends entries to the default type map, while `-defaulttypemap` replaces the existing default type map with the specified entries.

See Also: "Type Mapping Support for OPAQUE Types", "Type Mapping Support for Scalar Index-by Tables", and "Type Mapping Support Through PL/SQL Conversion Functions"

Here are some sample type map settings, from a properties file that uses the `-defaulttypemap` and `-adddefaulttypemap` options:

    jpub.defaulttypemap=SYS.XMLTYPE:oracle.xdb.XMLType
    jpub.adddefaulttypemap=BOOLEAN:boolean:INTEGER:
    SYS.SQLJUTL.INT2BOOL:SYS.SQLJUTL.BOOL2INT
    jpub.adddefaulttypemap=INTERVAL DAY TO SECOND:String:CHAR:
    SYS.SQLJUTL.CHAR2IDS:SYS.SQLJUTL.IDS2CHAR
    jpub.adddefaulttypemap=INTERVAL YEAR TO MONTH:String:CHAR:
    SYS.SQLJUTL.CHAR2IYM:SYS.SQLJUTL.IYM2CHAR

Be aware that you must avoid conflicts between the default type map and user type map.

#### 6.1.7.1 Addi ng an Entry to the Default Type Map

Use the `-adddefaulttypemap` option to append an entry or a comma-delimited list of entries to the JPublisher default type map. In addition, JPublisher uses this option internally. The syntax of this option is:

    -adddefaulttypemap=list_of_typemap_entries

#### 6.1.7.2 Additio nal Entry to the User Type Map

Use the `-addtypemap` option to append an entry or a comma-delimited list of entries to the JPublisher user type map. The syntax of this option is:

    -addtypemap=list_of_typemap_entries

#### 6.1.7.3 Defa ult Type Map for JPublisher

JPublisher uses the `-defaulttypemap` option internally to set up predefined type map entries in the default type map. The syntax of this option is:

    -defaulttypemap=list_of_typemap_entries

The difference between the `-adddefaulttypemap` option and the `-defaulttypemap` option is that `-adddefaulttypemap` appends entries to the default type map, while `-defaulttypemap` replaces the existing default type map with the specified entries. To clear the default type map, use the following setting:

    -defaulttypemap=

You may want to do this to avoid conflicts between the default type map and the user type map, for example.

See Also: "JPublisher User Type Map and Default Type Map" for additional information, including a caution about conflicts between the type maps.

#### 6.1.7.4 Replac ement of the JPublisher Type Map

Use the `-typemap` option to specify an entry or a comma-delimited list of entries to set up the user type map. The syntax of this option is:

    -typemap=list_of_typemap_entries

The difference between the `-typemap` option and the `-addtypemap` option is that `-typemap` replaces the existing user type map with the specified entries and `-addtypemap` appends entries to the user type map. To clear the user type map, use the following setting.

    -typemap=

You may want to do this to avoid conflicts between the default type map and the user type map, for example.

### 6.1.8 Java Code-Ge neration Options

This section documents options that specify JPublisher characteristics and behavior for Java code generation. For example, there are options to accomplish the following:

- Filter generated code according to parameter modes or parameter types

- Ensure that generated code conforms to the JavaBeans specification

- Specify naming patterns

- Specify how stubs are generated for user subclasses

- Specify whether generated code is serializable

The following options are described in alphabetical order: `-access`, `-case`, `-filtermodes`, `-filtertypes`, `-generatebean`, `-genpattern`, `-gensubclass`, `-methods`, `-omit_schema_names`, `-outarguments`, `-package`, `-serializable`, and `-tostring`.

#### 6.1.8.1 Metho d Access

The `-access` option determines the access modifier that JPublisher includes in generated constructors, attribute setter and getter methods, member methods on object wrapper classes, and methods on PL/SQL packages. The syntax of this option is:

    -access={public|protected|package}

JPublisher uses the possible option settings as follows:

- `public`

  Methods are generated with the `public` access modifier. This is the default option setting.

- `protected`

  Methods are generated with the `protected` access modifier.

- `package`

  The access modifier is omitted, so generated methods are local to the package.

You may want to use a setting of `-access=protected` or `-access=package` if you want to control the usage of the generated JPublisher wrapper classes. For example, when you provide customized versions of the wrapper classes as subclasses of the JPublisher-generated classes, but do not want to provide access to the generated superclasses.

You can specify the `-access` option on the command line or in a properties file.

Note: Wrapper classes for object references and `VARRAY` and nested table types are not affected by the value of the `-access` option.

#### 6.1.8.2 Case of Ja va Identifiers

For class or attribute names that you do not specify in an `INPUT` file or on the command line, the `-case` option affects the case of Java identifiers that JPublisher generates, including class names, method names, attribute names embedded within `get` `XXX``()` and `set` `XXX``()` method names, and arguments of generated method names. The syntax of this option is:

    -case={mixed|same|lower|upper}

Table 6-6 describes the possible values for the `-case` option.

Table 6-6 Values for the -case Option

-case Option Value | Description
--- | ---
`mixed` (default) | The first letter of every word unit of a class name or of every word unit after the first word unit of a method name is in uppercase. All other characters are in lowercase. An underscore (_), a dollar sign ($), or any character illegal in Java constitutes a word unit boundary and is removed without warning. A word unit boundary also occurs after `get` or `set` in a method name.
`same` | JPublisher does not change the case of letters from the way they are represented in the database. Underscores and dollar signs are retained. JPublisher removes any other character illegal in Java and issues a warning message.
`upper` | JPublisher converts lowercase letters to uppercase and retains underscores and dollar signs. It removes any other character illegal in Java and issues a warning message.
`lower` | JPublisher converts uppercase letters to lowercase and retains underscores and dollar signs. It removes any other character illegal in Java and issues a warning message.

For class or attribute names that you specify through JPublisher options or the `INPUT` file, JPublisher retains the case of the letters in the specified name and overrides the `-case` option.

#### 6.1.8.3 Meth od Filtering According to Parameter Modes

In some cases, particularly for generating code for Web services, not all parameter modes are supported in method signatures or attributes for the target usage of your code. The `-filtermodes` option enables you to filter generated code according to parameter modes. The syntax of this option is:

    -filtermodes=list_of_modes_to_filter_out_or_filter_in

You can specify the following for the `-filtermodes` option:

- `in`

- `out`

- `inout`

- `return`

Start the option setting with a `1` to include all possibilities by default, which would mean no filtering. Then list specific modes or types each followed by a minus sign (`-`), indicating that the mode or type should be excluded. Alternatively, start with a `0` to include no possibilities by default, which would mean total filtering, then list specific modes or types each followed by a plus sign (`+`), indicating that the mode or type should be allowed.

The following examples would have the same result, allowing only methods that have parameters of the `in` or `return` mode. Separate the entries by commas.

    -filtermodes=0,in+,return+

    -filtermodes=1,out-,inout-

#### 6.1.8.4 Meth od Filtering According to Parameter Types

In some cases, particularly for generating code for Web services, not all parameter types are supported in method signatures or attributes for the target usage of your code. The `-filtertypes` option enables you to filter generated code according to parameter types. The syntax of this option is:

    -filtertypes=list_of_types_to_filter_out_or_filter_in

You can specify the following settings for the `-filtertypes` option:

- Any qualified Java type name

  Specify package and class, such as `java.sql.SQLData`, `oracle.sql.ORAData`.

- `.ORADATA`

  This setting indicates any `ORAData` or `SQLData` implementations.

- `.STRUCT`, `.ARRAY`, `.OPAQUE`, `.REF`

  Each of these settings indicates any types that implement `ORAData` or `SQLData` with the corresponding `_SQL_TYPECODE` specification.

- `.CURSOR`

  This setting indicates any SQLJ iterator types and `java.sql.ResultSet`.

- `.INDEXBY`

  This setting indicates any indexed-by table types.

- `.ORACLESQL`

  This setting indicates all `oracle.sql.``XXX` types.

Start the option setting with a `1` to include all possibilities by default, indicating no filtering, then list specific modes or types each followed by a minus sign (`-`), indicating that the mode or type should be excluded. Alternatively, start with a `0` to include no possibilities by default, indicating total filtering, then list specific modes or types each followed by a plus sign (`+`), indicating that the mode or type should be allowed.

This first example filters out only `.ORADATA` and `.ORACLESQL`. The second example filters everything except `.CURSOR` and `.INDEXBY`:

    -filtertypes=1,.ORADATA-,.ORACLESQL-

    -filtertypes=0,.CURSOR+,.INDEXBY+

The `.STRUCT`, `.ARRAY`, `.OPAQUE`, and `.REF` settings are subcategories of the `.ORADATA` setting. Therefore, you can have specifications, such as the following, which filters out all `ORAData` and `SQLData` types except those with a typecode of `STRUCT`:

    -filtertypes=1,.ORADATA-,.STRUCT+

Alternatively, to allow `ORAData` or `SQLData` types in general, with the exception of those with a typecode of `ARRAY` or `REF`:

    -filtertypes=0,.ORADATA+,.ARRAY-,.REF-

#### 6.1.8.5 Code Gen eration Adhe rence to the JavaBeans Specification

The `-generatebean` option is a flag that you can use to ensure that generated classes follow the JavaBeans specification. The syntax of this option is:

    -generatebean={true|false}

The default setting is `-generatebean=false`. With the `-generatebean=true` setting, some generated methods are renamed so that they are not assumed to be JavaBean property getter or setter methods. This is accomplished by prefixing the method names with an underscore (`_`). For example, for classes generated from SQL table types, `VARRAY`, or indexed-by table, method names are changed as follows.

Method names are changed from:

    public int getBaseType() throws SQLException;
    public int getBaseTypeName() throws SQLException;
    public int getDescriptor() throws SQLException;

to:

    public int _getBaseType() throws SQLException;
    public String _getBaseTypeName() throws SQLException;
    public ArrayDecscriptor _getDescriptor() throws SQLException;

The changes in return types are necessary because the JavaBeans specification says that a getter method must return a bean property, but `getBaseType()`, `getBaseTypeName()`, and `getDescriptor()` do not return a bean property.

#### 6.1.8.6 Class a nd Interface Naming Pattern

It is often desirable to follow a certain naming pattern for Java classes, user subclasses, and interfaces generated for user-defined SQL types or packages. The `-genpattern` option, which you can use in conjunction with the `-sql` or `-sqlstatement` option, enables you to define such patterns conveniently and generically. The syntax of this option is:

    -genpattern=pattern_specifications

Consider the following explicit command-line options:

    -sql=PERSON:PersonBase:PersonUser#Person
    -sql=STUDENT:StudentBase:StudentUser#Student
    -sql=GRAD_STUDENT:GradStudentBase:GradStudentUser#GradStudent

The following pair of options is equivalent to the preceding set of options:

    -genpattern=%1Base:%1User#%1
    -sql=PERSON,STUDENT,GRAD_STUDENT

By definition, `%1` refers to the default base names that JPublisher would create for each SQL type. By default, JPublisher would create the `Person` Java type for the `PERSON` SQL type, the `Student` Java type for the `STUDENT` SQL type, and the `GradStudent` Java type for the `GRAD_STUDENT` SQL type. So `%1Base` becomes `PersonBase`, `StudentBase`, and `GradStudentBase`, respectively. Similar results are produced for `%1User`.

If the `-sql` option specifies the output names, then `%2`, by definition, refers to the specified names. For example, the following pair of options has the same effect as the earlier pair:

    -genpattern=%2Base:%2User#%2
    -sql=PERSON:Person,STUDENT:Student,GRAD_STUDENT:GradStudent

Note: This is the pattern expected for Web services. Specify an output name and use that as the interface name, and append `Base` for the generated class and `User` for the user subclass.

The following example combines the `-genpattern` option with the `-sqlstatement` option:

    -sqlstatement.class=SqlStmts -genpattern=%2Base:%2User:%2

These settings are equivalent to the following:

    -sqlstatement.class=SqlStmtsBase:SqlStmtsUser#SqlStmts

#### 6.1.8.7 Gene ration of User Subclasses

The value of the `-gensubclass` option determines whether JPublisher generates initial source files for user-provided subclasses and, if so, what format these subclasses should have. The syntax of this option is:

    -gensubclass={true|false|force|call-super}

For `-gensubclass=true`, which is the default, JPublisher generates code for the subclass only if it finds that no source file is present for the user subclass. The `-gensubclass=false` setting results in JPublisher not generating any code for user subclasses.

For `-gensubclass=force`, JPublisher always generates code for user subclasses. It overwrites any existing content in the corresponding `.java` and `.class` files if they already exist. Use this setting with caution.

The setting `-gensubclass=call-super` is equivalent to `-gensubclass=true`, except that JPublisher generates slightly different code. By default, JPublisher generates only constructors and methods necessary for implementing an interface, for example, the `ORAData` interface. JPublisher indicates how superclass methods or attribute setter and getter methods can be called, but places this code inside comments. With the `call-super` setting, all getters, setters, and other methods are generated.

The idea is that you can specify this setting if you use Java development tools based on class introspection. Only methods relating to SQL object attributes and SQL object methods are of interest, and JPublisher implementation details remain hidden. In this case you can point the tool at the generated user subclass.

You can specify the `-gensubclass` option on the command line or in a properties file.

#### 6.1.8.8 Gen eration of Package Classes and Wrapper Methods

The `-methods` option determines whether:

- JPublisher generates wrapper methods for methods, or stored procedures in SQL object types and PL/SQL packages.

- Overloaded method names are allowed.

- Methods will attempt to reestablish a JDBC connection if an `SQLException` is caught.

The syntax for the `-methods` option is:

    -methods={all|none|named|always,overload|unique,noretry|retry}

For `-methods=all`, which is the default setting among the first group of settings, JPublisher generates wrapper methods for all the methods in the SQL object types and PL/SQL packages it processes. This results in generation of a SQLJ class if the underlying SQL object or package actually defines methods and if not, a non-SQLJ class. Prior to Oracle Database 10g, SQLJ classes were always generated for the `all` setting.

For `-methods=none`, JPublisher does not generate wrapper methods. In this case, JPublisher does not generate classes for PL/SQL packages, because they would not be useful without wrapper methods.

For `-methods=named`, JPublisher generates wrapper methods only for the methods explicitly named in the `INPUT` file.

The `-methods=always` setting also results in wrapper methods being generated. However, for backward compatibility with the Oracle8i and Oracle9i JPublisher versions, this setting always results in SQLJ classes being generated for all SQL object types, regardless of whether the types define methods.

Note: For backward compatibility, JPublisher also supports the setting `true` as equivalent to `all`, the setting `false` as equivalent to `none`, and the setting `some` as equivalent to `named`.

Among the `overload` and `unique` settings, `-methods=overload` is the default and specifies that method names in the generated code can be overloaded, such as the following:

    int foo(int);
    int foo(String);

Alternatively, the `-methods=unique` setting specifies that all method names must be unique. This is required for Web services. Consider the following functions:

    function foo (a VARCHAR2(40)) return VARCHAR2;
    function foo ( x int, y int) return int;

With the default `-methods=overload` setting, these functions are published as follows:

    String foo(String a);
    java.math.BigDecimal foo(java.math.BigDecimal x, java.math.BigDecimal y);

With the `-methods=unique` setting, these functions are published using a method-renaming mechanism based on the first letter of the return type and argument types, as shown in the following example:

    String foo(String a);
    java.math.BigDecimal fooBBB(java.math.BigDecimal x, java.math.BigDecimal y);

See Also: "Translation of Overloaded Methods"

With the `-methods=retry` setting, JPublisher generates constructors with `DataSource` arguments and extra code for each method published. A JDBC operation in a method is enclosed within a `try...catch` block. If an `SQLException` is raised when the method is processed, then the extra code will attempt to reestablish the JDBC connection and process the SQL operation again. If the attempt to reconnect fails, then the original `SQLException` is thrown again.

For `-methods=retry`, JPublisher generates code different from that generated for `-methods=noretry`, in two respects:

- An additional constructor, which takes a `DataSource` object as parameter, is generated. The `DataSource` object is used to get a new connection at operation invocation time.

- A new JDBC connection is requested if an `SQLException` is thrown.

The `-methods=retry` setting takes effect only for PL/SQL stored procedures, SQL statements, AQ, and Web services call-ins for Java classes.

Note: The use of `oracle.jdbc.pool.OracleDataSource` requires JDK 1.3 or later.

To specify a setting of `all`, `none`, `named`, or `always` at the same time as you specify a setting of `overload` or `unique` and a setting for `retry` or `noretry`, use a comma to separate the settings. This is shown in the following example:

    -methods=always,unique,retry

You can specify the `-methods` option on the command line or in a properties file.

#### 6.1.8.9 Omission of Sche ma Name from Name References

In publishing user-defined SQL types, such as objects and collections, when JPublisher references the type names in Java wrapper classes, it generally qualifies the type names with the database schema name, such as `SCOTT.EMPLOYEE` for the `EMPLOYEE` type in the `SCOTT` schema.

However, by specifying the `-omit_schema_names` option, you instruct JPublisher not to qualify SQL type names with schema names. The syntax of this option is:

    -omit_schema_names

When this option is specified, names are qualified with a schema name only under the following circumstances:

- You declare the user-defined SQL type in a schema other than the one to which JPublisher is connected. A type from another schema always requires a schema name to identify it.

- You declare the user-defined SQL type with a schema name on the command line or in an `INPUT` file. The use of a schema name with the type name on the command line or `INPUT` file overrides the `-omit_schema_names` option.

Omitting the schema name makes it possible for you to use classes generated by JPublisher when you connect to a schema other than the one used when JPublisher is invoked, as long as the SQL types that you use are declared identically in the two schemas.

`ORAData` and `SQLData` classes generated by JPublisher include a `static final String` field that names the user-defined SQL type matching the generated class. When the code generated by JPublisher is processed, the SQL type name in the generated code is used to locate the SQL type in the database. If the SQL type name does not include the schema name, then the type is looked up in the schema associated with the current connection when the code generated by JPublisher is processed. If the SQL type name includes the schema name, then the type is looked up in that schema.

When the `-omit_schema_names` option is enabled, JPublisher generates the following code in the Java wrapper class for a SQL object type and similar code to wrap a collection type:

    public Datum toDatum(Connection c) throws SQLException
        {
          if (__schemaName != null)
          {
            return _struct.toDatum(c, __schemaName + "." + _SQL_NAME);
          }
          return _struct.toDatum(c, typeName);
        }
        private String __schemaName = null;
        public void __setSchemaName(String schemaName) { __schemaName = schemaName; }
      }

The `__setSchemaName()` method enables you to explicitly set the schema name at run time so that SQL type names can be qualified by schema even if JPublisher was run with the `-omit_schema_names` option enabled. Being qualified by schema is necessary if a SQL type needs to be accessed from another schema.

Note: Although this option behaves as a boolean option, you cannot specify `-omit_schema_names=true` or `-omit_schema_names=false`. Specify `-omit_schema_names` to enable it, and do nothing to leave it disabled.

#### 6.1.8.10 Holde r Types for Output Arguments

There are no `OUT` or `IN OUT` designations in Java, but values can be returned through holders. In JPublisher, you can specify one of three alternatives for holders:

- Arrays, which is the default

- JAX-RPC holder types

- Function returns

The `-outarguments` option enables you to specify the mechanism to use, through a setting of `array`, `holder`, or `return`, respectively. This feature is particularly useful for Web services. The syntax of this option is:

    -outarguments={array|holder|return}

See Also: "Treatment of Output Parameters"

#### 6.1.8.11 Name for Ge nerated Java Package

The `-package` option specifies the name of the Java package that JPublisher generates. The name appears in a package declaration in each generated class. The syntax for this option is:

    -package=package_name

If you use the `-dir` and `-d` options, the directory structure in which JPublisher places the generated files reflects the package name as well as the `-dir` and `-d` settings.

Notes: If there are conflicting package settings between a `-package` option setting and a package setting in the `INPUT` file, the precedence depends on the order in which the `-input` and `-package` options appear on the command line. The `-package` setting takes precedence if that option is after the `-input` option. Otherwise, the `INPUT` file setting takes precedence. If you do not use the `-dir` and `-d` options, or if you explicitly give them empty settings, then JPublisher places all generated files directly in the current directory, with no package hierarchy, regardless of the `-package` setting.

See Also: "Output Directories for Generated Source and Class Files"

Example 1 Consider the following command:

    % jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person ...

JPublisher generates the files `/a/b/c/d/Person.java` and `/a/b/c/d/Person.class`.

In addition, the `Person` class includes the following package declaration:

    package c.d;

Example 2 Now consider the following command:

    % jpub -dir=/a/b -d=/a/b -package=c.d -sql=PERSON:Person -input=myinputfile

Assume that `myinputfile` includes the following:

    SQL PERSON AS e.f.Person

In this case, the package information in the `INPUT` file overrides the `-package` option on the command line. JPublisher generates the files `/a/b/e/f/Person.java` and `/a/b/e/f/Person.class`, with the `Person` class including the following package declaration:

    package e.f;

If you do not specify a package name, then JPublisher does not generate any package declaration. The output `.java` files are placed directly into the directory specified by the `-dir` option or into the current directory by default. The output `.class` files are placed directly into the directory specified by the `-d` option or into the current directory.

Sometimes JPublisher translates a type that you do not explicitly request, because the type is required by another type that is translated. For example, it may be an attribute of the requested type. In this case, the `.java` and `.class` files declaring the required type are also placed into the package specified on the command line, in a properties file or the `INPUT` file.

By contrast, JPublisher never translates packages or stored procedures that you do not explicitly request, because packages or stored procedures are never strictly required by SQL types or by other packages or stored procedures.

#### 6.1.8.12 Serializ ability of Generated Object Wrapper Classes

The `-serializable` option specifies whether the Java classes that JPublisher generates for SQL object types implement the `java.io.Serializable` interface. The default setting is `-serializable=false`. The syntax for this option is:

    -serializable={true|false}

Please note the following if you choose to set `-serializable=true`:

- Not all object attributes are serializable. In particular, none of the Oracle LOB types, such as `oracle.sql.BLOB`, `oracle.sql.CLOB`, or `oracle.sql.BFILE`, can be serialized. Whenever you serialize objects with such attributes, the corresponding attribute values are initialized to `null` after deserialization.

- If you use object attributes of type `java.sql.Blob` or `java.sql.Clob`, then the code generated by JPublisher requires that the Oracle JDBC rowset implementation be available in the classpath. This is provided in the `ocrs12.jar` library at `ORACLE_HOME``/jdbc/lib`. In this case, the underlying value of `Clob` and `Blob` objects is materialized, serialized, and subsequently retrieved.

- Whenever you deserialize objects containing attributes that are object references, the underlying connection is lost, and you cannot issue `setValue()` or `getValue()` calls on the reference. For this reason, JPublisher generates the following method into your Java classes whenever you specify `-serializable=true`:

      void restoreConnection(Connection)

  After deserialization, call this method once for a given object or object reference to restore the current connection into the reference or, respectively, into all transitively embedded references.

#### 6.1.8.13 Gener ation of toString() Method on Object Wrapper Classes

You can use the `-tostring` flag to tell JPublisher to generate an additional `toString()` method for printing out an object value. The output resembles SQL code you would use to construct the object. The default setting is `false`. The syntax for this option is:

    -tostring={true|false}

#### 6.1.8.14 Rename main Method

You can use `-nomain=true` to avoid generating Java methods with the signature `main(String[])`. This option applies to SQL publishing and server-side Java class publishing. The syntax for this option is:

    -nomain[=true|false]

The `-dbjava` option automatically sets `-nomain=true` because of Java stored procedure limitation. In case a method with the signature `main(String[])` is to be generated with the `-nomain=true` setting, then JPublisher will rename the method, for example, into `main0(Stringp[])`.

The default setting is:

    -nomain=false

### 6.1.9 PL/SQL Code Generation Options

This section documents the following options that specify JPublisher behavior in generating PL/SQL code:

- `-overwritedbtypes`

  Specifies whether naming conflicts are checked before creating SQL types.

- `-plsqlfile`

  Specifies scripts to use in creating and dropping SQL types and PL/SQL packages.

- `-plsqlmap`

  Specifies whether PL/SQL wrapper functions are generated

- `-plsqlpackage`

  Specifies the name of the PL/SQL package in which JPublisher generates PL/SQL call specs, conversion functions, wrapper functions, and table functions.

These options are mostly used to support Java calls to stored procedures that use PL/SQL types. The options specify the creation and use of corresponding SQL types and the creation and use of PL/SQL conversion functions and PL/SQL wrapper functions that use the corresponding SQL types for input or output. This enables access through JDBC.

#### 6.1.9.1 Generation of SQL types

JPublisher may generate new SQL types when publishing PL/SQL types and generating PL/SQL wrappers for server-side Java classes. The `-overwritedbtypes` option determines how JPublisher names the generated SQL types. The syntax for this option is:

    -overwritedbtypes={true|false}

Prior to Oracle Database 10g release 2 (10.2), JPublisher checked the database for naming conflicts and chose a name, which was not already in use, for the generated SQL type. In Oracle Database 10g release 2 (10.2), JPublisher generates SQL type names by default, regardless of the existing type names in the database. The `-overwritedbtypes=true` setting, which is the default, overwrites the existing types if the type name is the same as that of the generated SQL type. This enables JPublisher to generate exactly the same PL/SQL wrappers over different runs.

To ensure that JPublisher does not overwrite any type inside the database while executing the generated PL/SQL wrapper, you must explicitly specify `-overwritedbtypes=false`.

A frequently reported problem in releases prior to Oracle Database 10g release 2 (10.2) is that after the generated PL/SQL wrapper is processed, rerunning the JPublisher command generates a different set of SQL types. A workaround for this problem is to run the PL/SQL dropper script before the JPublisher command is rerun.

#### 6.1.9.2 File Nam es for PL/SQL Scripts

The `-plsqlfile` option specifies the name of a wrapper script and a dropper script generated by JPublisher. The syntax for this option is:

    -plsqlfile=plsql_wrapper_script,plsql_dropper_script

The wrapper script contains instructions to create SQL types to map to PL/SQL types and instructions to create the PL/SQL package that JPublisher uses for any PL/SQL wrappers or call specs, conversion functions, wrapper functions, and table functions. The dropper script contains instructions to drop these entities.

You must load the generated files into the database, using SQL*Plus, for example, and run the wrapper script to install the types and package in the database.

If the files already exist, then they are overwritten. If no file names are specified, then JPublisher writes to files named `plsql_wrapper.sql` and `plsql_dropper.sql`.

JPublisher writes a note about the generated scripts, such as the following:

    J2T-138, NOTE: Wrote PL/SQL package JPUB_PLSQL_WRAPPER to
    file plsql_wrapper.sql. Wrote the dropping script to file plsql_dropper.sql.

#### 6.1.9.3 Gener ation of PL/SQL Wrapper Functions

The `-plsqlmap` option specifies whether JPublisher generates wrapper functions for stored procedures that use PL/SQL types. Each wrapper function calls the corresponding stored procedure and invokes the appropriate PL/SQL conversion functions for PL/SQL input or output of the stored procedure. Only the corresponding SQL types are exposed to Java. The syntax for this option is:

    -plsqlmap={true|false|always}

The setting can be any of the following:

- `true`

  This is the default. JPublisher generates PL/SQL wrapper functions only as needed. For any given stored procedure, if the Java code to call it and convert its PL/SQL types directly is simple enough and the PL/SQL types are used only as `IN` parameters or for the function return, then the generated code calls the stored procedure directly. It processes the PL/SQL input or output through the appropriate conversion functions.

- `false`

  JPublisher does not generate PL/SQL wrapper functions. If it encounters a PL/SQL type in a signature that cannot be supported by direct call and conversion, then it skips generation of Java code for the particular stored procedure.

- `always`

  JPublisher generates a PL/SQL wrapper function for every stored procedure that uses a PL/SQL type. This is useful for generating a proxy PL/SQL package that complements an original PL/SQL package, providing Java-accessible signatures for those functions or procedures that are inaccessible from Java in the original package.

See Also: "Type Mapping Support Through PL/SQL Conversion Functions" and "Direct Use of PL/SQL Conversion Functions Versus Use of Wrapper Functions"

#### 6.1.9.4 Packa ge for Generated PL/SQL Code

The `-plsqlpackage` option specifies the name of the PL/SQL package into which JPublisher places any generated PL/SQL code. This includes PL/SQL wrappers or call specifications, conversion functions to convert between PL/SQL and SQL types, wrapper functions to wrap stored procedures that use PL/SQL types, and table functions. The syntax for this option is:

    -plsqlpackage=name_of_PLSQL_package

By default, JPublisher uses the package `JPUB_PLSQL_WRAPPER`.

Note: You must create this package in the database by running the SQL script generated by JPublisher.

#### 6.1.9.5 Package for PL/SQL Index-By Tables

Use `-plsqlindextable=array` or `-plsqlindextable=``int` to specify that PL/SQL index-by table of numeric and character types be mapped to Java array. The syntax for this option is:

    -plsqlindextable=array|custom|int

The `int` specification defines the capacity of the Java array. The default capacity is 32768. The `-plsqlindextable=custom` setting specifies that PL/SQL index-by table be mapped to custom JDBC types, such as a class implementing `ORAData`.

The default setting is:

    -plsqlindextable=custom

### 6.1.10 Input/Outp ut Options

This section documents options related to JPublisher input and output files and locations. These are listed in the order in which they are discussed:

- `-compile`

  Use this option if you want to suppress compilation, and optionally, SQLJ translation, if JPublisher is in a backward-compatibility mode.

- `-dir`

  Use this option to specify where the generated source files are placed.

- `-d`

  Use this option to specify where the compiled class files are placed.

- `-encoding`

  Use this option to specify the Java character encoding of the `INPUT` file that JPublisher reads and the `.sqlj` and `.java` files that JPublisher writes.

#### 6.1.10.1 No Com pilation or Translation

Use the `-compile` option to suppress the compilation of the generated `.java` files and, for backward-compatibility modes, to optionally suppress the translation of generated `.sqlj` files. The syntax for this option is:

    -compile={true|false|notranslate}

With the default `true` setting, all generated classes are compiled into `.class` files. If you are in a backward-compatibility mode, then you can use the `-compile=notranslate` setting to suppress SQLJ translation and Java compilation of generated source files. This leaves you with `.sqlj` output from JPublisher, which you can translate and compile manually by using either the JPublisher `-sqlj` option or the SQLJ command-line utility directly. You can also use the `-compile=false` setting to proceed with SQLJ translation, but skip Java compilation. This leaves you with `.java` output from JPublisher, which you can compile manually.

If you are not in a backward-compatibility mode, such as if you use the default `-compatible=oradata` setting, then you can use a setting of `-compile=false` to skip compilation. In this scenario, the `notranslate` setting is not supported, because visible `.sqlj` files are not produced if you are not in a backward-compatibility mode.

See Also: "Backward Compatibility Option" and "Option to Access SQLJ Functionality"

#### 6.1.10.2 Output Dir ectories for Generated Source and Class Files

Use the `-dir` option to specify the root of the directory tree within which JPublisher places the `.java` source files or the `.sqlj` source files for backward-compatibility modes. The syntax for this option is:

    -dir=directory_path
    -d=directory_path

A setting of a period (`.`) explicitly specifies the current directory as the root of the directory tree. Similarly, use the `-d` option to specify the root of the directory tree within which JPublisher places compiled `.class` files, with the same functionality for a period (`.`) setting.

For each option with any nonempty setting, JPublisher also uses package information from the `-package` option or any package name included in an `SQL` option setting in the `INPUT` file. This information is used to determine the complete directory hierarchy for generated files.

See Also: "Name for Generated Java Package"

For example, consider the following JPublisher command:

    % jpub -user=scott/tiger -d=myclasses -dir=mysource -package=a.b.c
           -sql=PERSON:Person,STUDENT:Student

This results in the following output, relative to the current directory:

    mysource/a/b/c/Person.java
    mysource/a/b/c/PersonRef.java
    mysource/a/b/c/Student.java
    mysource/a/b/c/StudentRef.java

    myclasses/a/b/c/Person.class
    myclasses/a/b/c/PersonRef.class
    myclasses/a/b/c/Student.class
    myclasses/a/b/c/StudentRef.class

By default, source and class files are placed directly into the current directory, with no package hierarchy, regardless of the `-package` setting or any package specification in the `INPUT` file.

You can also explicitly specify this behavior with empty settings:

    %jpub ... -d= -dir=

You can set these options on the command line or in a properties file.

Note: SQLJ has `-dir` and `-d` options as well, with the same functionality. However, when you use the JPublisher `-sqlj` option to specify SQLJ settings, use the JPublisher `-dir` and `-d` options, which take precedence over any SQLJ `-dir` and `-d` settings.

#### 6.1.10.3 Java Character Encoding

The `-encoding` option specifies the Java character encoding of the `INPUT` file that JPublisher reads and the source files that JPublisher writes. The default encoding is the value of the `file.encoding` system property or `8859_1` (ISO Latin-1), if this property is not set. The syntax for this option is:

    -encoding=name_of_character_encoding

As a general rule, you do not have to set this option unless you specify an encoding for the SQLJ translator and Java compiler, which you can do with a SQLJ `-encoding` setting through the JPublisher `-sqlj` option. In this scenario, you should specify the same encoding for JPublisher as for SQLJ and the compiler.

You can use the `-encoding` option to specify any character encoding supported by your Java environment. If you are using the Sun Microsystems JDK, these options are listed in the `native2ascii` documentation, which you can find at the following URL:

`http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/native2ascii.html`

Note: Encoding settings, either set through the JPublisher `-encoding` option or the Java `file.encoding` setting, do not apply to Java properties files, including those specified through the JPublisher `-props` option. Properties files always use the `8859_1` encoding. This is a feature of Java in general and not JPublisher in particular. However, you can use Unicode escape sequences in a properties file.

### 6.1.11 Optio ns to Facilitate Web Services Call-Outs

This section documents options and related concepts for accessing Java classes from server-side Java or PL/SQL. In particular, these options may be used to access Web services client code from inside the database, referred to as Web services call-outs. This section comprises the following topics:

- WSDL Document for Java and PL/SQL Wrapper Generation

- Web Services Endpoint

- Proxy URL for WSDL

- Superuser for Permissions to Run Client Proxies

The following list is a summary of the options relevant to Web services call-outs and how they relate to each other:

- `-proxyclasses=``class1,class2,...,classN`

  This option specifies Java classes for which Java and PL/SQL wrappers will be generated. For Web services, this option is used behind the scenes by the `-proxywsdl` option and is set automatically to process generated client proxy classes.

  Alternatively, you can use this option directly, for general purposes, when you want to create Java and PL/SQL wrappers for Java classes.

  The `-proxyclasses` option takes the `-proxyopts` setting as input.

- `-proxyopts=``setting1,setting2,...`

  This option specifies JPublisher behavior in generating wrapper classes and PL/SQL wrappers. This is usually, but not necessarily, for Web services. For typical usage of the `-proxywsdl` option, the `-proxyopts` default setting is sufficient. If you directly use the `-proxyclasses` option, then you may want specific `-proxyopts` settings.

- `-proxywsdl=``WSDL_URL`

  Use this option to generate Web services client proxy classes and appropriate Java and PL/SQL wrappers, given the WSDL document at the specified URL.

  The `-proxywsdl` option uses the `-proxyclasses` option behind the scenes and takes the `-proxyopts` setting as input.

- `-endpoint=``Web_services_endpoint`

  Use this option in conjunction with the `-proxywsdl` option to specify the Web services endpoint.

- `-httpproxy=``proxy_URL`

  Where the WSDL document is accessed through a firewall, use this option to specify a proxy URL to use in resolving the URL of the WSDL document.

- `-sysuser=``superuser_name/superuser_password`

  Use this option to specify the name and password for the superuser account used to grant permissions for the client proxy classes to access Web services using HTTP.

Notes: The features described here require the `dbwsclient.jar` library to be installed in Oracle Database 10g. Several previously existing JPublisher options are used in conjunction with wrapper generation as discussed here: `-dir`, `-d`, `-plsqlmap`, `-plsqlfile`, `-plsqlpackage`, and `-package`. You can also specify a database connection through the `-user` and `-url` options so that JPublisher can load generated entities into the database.

#### 6.1.11.1 WS DL Document for Java and PL/SQL Wrapper Generation

The syntax for the `-proxywsdl` option is:

    -proxywsdl=WSDL_URL

This option is used as follows:

    % jpub -proxywsdl=META-INF/HelloServiceEJB.wsdl ...

Given the Web services WSDL document at the specified URL, JPublisher directs the generation of Web services client proxy classes and generates appropriate Java and PL/SQL wrappers for Web services call-outs from the database. Classes to generate and process are determined from the WSDL document. JPublisher automatically sets the `-proxyclasses` option, uses the `-proxyopts` setting as input, and executes the following steps:

1. Invokes the Oracle Database Web services assembler tool to produce Web services client proxy classes based on the WSDL document. These classes use the Oracle Database Web services client run time to access the Web services specified in the WSDL document.

2. Creates Java wrapper classes for the Web services client proxy classes as appropriate or necessary. For each proxy class that has instance methods, a wrapper class is necessary to expose the instance methods as static methods. Even if there are no instance methods, a wrapper class is necessary if methods of the proxy class use anything other than Java primitive types in their calling sequences.

3. Creates PL/SQL wrappers for the generated classes, to make them accessible from PL/SQL. PL/SQL supports only static methods, so this step requires the wrapping of instance methods by static methods, This is performed in the previous step.

4. Loads generated code into the database assuming you have specified `-user` and `-url` settings and JPublisher has established a connection, unless you specifically bypass loading through the `-proxyopts=noload` setting.

Note: When using `-proxywsdl`: You must use the `-package` option to determine the package for generated Java classes. For `-proxyopts`, the default `jaxrpc` setting is sufficient for use with 10.0.x releases of Oracle Application Server 10g. This setting uses the singleton mechanism for publishing instance methods of the Web services client proxy classes. For use with the 9.0.4 release of Oracle Application Server 10g or with earlier releases, set `-proxyopts=soap`.

The `-endpoint` option is typically used in conjunction with the `-proxywsdl` option.

#### 6.1.11.2 Web Ser vices Endpoint

You can use the `-endpoint` option in conjunction with the `-proxywsdl` option to specify the Web services endpoint. The endpoint is the URL to which the Web service is deployed and from which the client accesses it. The syntax for this option is:

    -endpoint=Web_services_endpoint

Use this option as follows:

    % jpub -proxywsdl=META-INF/HelloServiceEJB.wsdl ...
           -endpoint=http://localhost:8888/javacallout/javacallout

With this command, the Java wrapper class generated by JPublisher includes the following code:

    ((Stub)m_port0)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
                         "http://localhost:8888/javacallout/javacallout");

Without the `-endpoint` option, there would instead be the following commented code:

    // Specify the endpoint and then uncomment the following statement:
          // ((Stub)m_port0)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,
          //                "<endpoint not provided>");

If you do not specify the endpoint in the JPublisher command line, then you must manually alter the generated wrapper class to uncomment this code and specify the appropriate endpoint.

#### 6.1.11.3 Pro xy URL for WSDL

If a WSDL document used for Web services call-outs is accessed through a firewall, use the `-httpproxy` option in conjunction with the `-proxywsdl` option to specify a proxy URL to use in resolving the URL of the WSDL document. The syntax for this option is:

    -httpproxy=proxy_URL

For example:

    % jpub ... -httpproxy=http://www-proxy.oracle.com:80

#### 6.1.11.4 Super user for Permissions to Run Client Proxies

Use the `-sysuser` option to specify the name and password of a superuser account. This account is used in running the JPublisher-generated PL/SQL script that grants permissions that allow client proxy classes to access Web services using HTTP. The syntax for this option is:

    -sysuser=superuser_name/superuser_password

For example:

    -sysuser=sys/change_on_install

Without a `-sysuser` setting, JPublisher does not load the generated script granting permissions. Instead, it asks you to execute the script separately.

If the `-url` setting specifies a thin driver, then you must set up a password file for `SYS`, which authorizes logon as `SYS`, through the thin driver. To set up a password file, you must:

1. Add the `remote_login_passwordfile` option to the database parameter file. You must use either of the following settings:

       remote_login_passwordfile=shared

       remote_login_passwordfile=exclusive

2. Create a password file, if you have not already created one. You can do this by running the following command, where `ORACLE_HOME``/dbs/` is an existing directory:

       orapwd file="ORACLE_HOME/dbs/orapwlsqlj1" password=change_on_install entries=100 force=y

3. Grant remote logon privileges to a user. This can be done as follows:

       % sqlplus /nolog
       SQL> CONN / AS sysdba
       Connected.
       SQL> GRANT sysdba TO scott;
       Grant succeeded.

See Also: Oracle Database JDBC Developer's Guide and Reference for details of setting up a remote `SYS` logon

### 6.1.12 Option to Ac cess SQLJ Functionality

This section documents the `-sqlj` option, which you can use to pass SQLJ options to the SQLJ translator through the JPublisher command line.

#### 6.1.12.1 Set tings for the SQLJ Translator

In Oracle Database 10g, SQLJ translation is automatic by default when you run JPublisher. Translation is transparent, with no visible `.sqlj` files resulting from JPublisher code generation.

However, you can still specify SQLJ settings for the JPublisher invocation of the SQLJ translator by using the JPublisher `-sqlj` option. The syntax for this option is:

    -sqlj=sqlj_options

For example:

    % jpub -user=scott/tiger -sqlj -optcols=true -optparams=true
           -optparamdefaults=datatype1(size1),datatype2(size)

Notes: There is no equal sign (`=`) following `-sqlj`. All other JPublisher options must precede the `-sqlj` option. Any option setting following `-sqlj` is taken to be a SQLJ option and is passed to the SQLJ translator. In the preceding example, `-optcols`, `-optparams`, and `-optparamdefaults` are SQLJ options.

You can also run JPublisher solely to translate `.sqlj` files that have already been produced explicitly, such as if you run JPublisher with the `-compatible=sqlj` setting, which skips the automatic SQLJ translation step and results in `.sqlj` output files from JPublisher. In this case, use no JPublisher options other than `-sqlj`. This is a way to accomplish manual SQLJ translation if the `sqlj` front-end script or executable is unavailable.

The commands following `-sqlj` are equivalent to the command you would give to the SQLJ translator utility directly. Here is an example:

    % jpub -sqlj -d=outclasses -warn=none -encoding=SJIS Foo.sqlj

This is equivalent to the following, if the SQLJ command-line translator is available:

    % sqlj -d=outclasses -warn=none -encoding=SJIS Foo.sqlj

Notes: As an alternative to specifying SQLJ option settings through the `-sqlj` option, you can specify them in the `sqlj.properties` file that JPublisher supports. The `-compiler-executable` option, if set, is passed to the SQLJ translator to specify the Java compiler that the translator will use to compile Java code.

### 6.1.13 Back ward Compatibility Option

This section documents the `-compatible` option, which you can use to specify any of the following:

- The interface for JPublisher to implement in generated classes

- Whether JPublisher should skip SQLJ translation, resulting in visible `.sqlj` output files

- A backward-compatibility mode to use JPublisher output in an Oracle9i or Oracle8i environment

See Also: "Backward Compatibility and Migration"

#### 6.1.13.1 Backw ard-Compatible Oracle Mapping for User-Defined Types

The `-compatible` option has two modes of operation:

- Through a setting of `oradata` or `customdatum`, you can explicitly specify an interface to be implemented by JPublisher-generated custom Java classes.

- Through a setting of `sqlj`, `8i`, `both8i`, or `9i`, you can specify a backward-compatibility mode.

You can select either of the two modes, but not both.

The syntax for this option is:

    -compatible={oradata|customdatum|both8i|8i|9i|10.1|sqlj}

Using -compatible to Specify an Interface

If `-usertypes=oracle`, then you have the option of setting `-compatible=customdatum`, to implement the deprecated `CustomDatum` interface in your generated classes for user-defined types, instead of the default `ORAData` interface. `CustomDatum` was replaced by `ORAData` in Oracle9i Database, but is still supported for backward compatibility.

The default setting to use the `ORAData` interface is `oradata`. If you set `-usertypes=jdbc`, then a `-compatible` setting of `customdatum` or `oradata` is ignored.

If you use JPublisher in a pre-Oracle9i Database environment, in which the `ORAData` interface is not supported, then the `CustomDatum` interface is used automatically if `-usertypes=oracle`. You will receive an informational warning if `-compatible=oradata`, but the generation will take place.

Using -compatible to Specify a Backward-Compatibility Mode

Use the `sqlj`, `10.1`, `9i`, `8i`, or `both8i` setting to specify a backward-compatibility mode.

The `-compatible=sqlj` setting instructs JPublisher to skip SQLJ translation and instead produce `.sqlj` files that you can work with directly. The `sqlj` setting has no effect on the generated code itself. To translate the resulting `.sqlj` files, you can use the SQLJ translator directly, if available, or use the JPublisher `-sqlj` option.

See Also: "Option to Access SQLJ Functionality"

The `-compatibility=10.1` setting specifies Oracle Database 10g release 1 (10.1) compatibility mode. In this mode, the JPublisher option `-dbjava` behaves the same as `-java` in Oracle Database 10g release 1 (10.1).

The `-compatibility=9i` setting specifies Oracle9i compatibility mode. In this mode, JPublisher generates `.sqlj` files with the same code as would be generated by the Oracle9i version.

The `-compatible=8i` setting specifies Oracle8i compatibility mode. This mode uses the `CustomDatum` interface, generating `.sqlj` files with the same code that would be generated by Oracle8i versions of JPublisher. The `8i` setting is equivalent to setting several individual JPublisher options for backward compatibility to Oracle8i. For example, behavior of method generation is equivalent to that for `-methods=always`, and generation of connection context declarations is equivalent to that for `-context=generated`.

The `-compatible=both8i` setting is for an alternative Oracle8i compatibility mode. With this setting, wrapper classes are generated to implement both the `ORAData` and `CustomDatum` interfaces. Code is generated as it would have been by the Oracle8i version of JPublisher. This setting is generally preferred over the `-compatible=8i` setting, because support for `ORAData` is required for programs running in the middle tier, such as in Oracle Application Server. However, using `ORAData` requires an Oracle9i release 1 (9.0.1) or later JDBC driver.

Note: In any compatibility mode that results in the generation of visible `.sqlj` files, remember that if you are generating Java wrapper classes for a SQL type hierarchy and any of the types contains stored procedures, then, by default, JPublisher generates `.sqlj` files for all the SQL types, and not just the types that have stored procedures.

### 6.1.14 Java Enviro nment Options

This section discusses JPublisher options that you can use to determine the Java environment:

- The `-classpath` option specifies the Java classpath that JPublisher and SQLJ use to resolve classes during translation and compilation.

- The `-compiler-executable` option specifies the Java compiler for compiling the code generated by JPublisher.

- The `-vm` option specifies the JVM through which JPublisher is invoked.

In a UNIX environment, the `jpub` script specifies the location of the Java executable that runs JPublisher. This script is generated at the time you install your database or application server instance. If the `jpub` script uses a Java version prior to JDK 1.4, then some JPublisher functionality for Web services, such as call-outs and mapping to the `SYS.XMLType`, are unavailable.

#### 6.1.14.1 Class path for Translation and Compilation

Use the `-classpath` option to specify the Java classpath for JPublisher to use in resolving Java source and classes during translation and compilation. The syntax for this option is:

    -classpath=path1:path2:...:pathN

The following command shows an example of its usage, adding new paths to the existing classpath:

    % jpub -user=scott/tiger -sql=PERSON:Person,STUDENT:Student
           -classpath=.:$ORACLE_HOME/jdbc/lib/ocrs12.jar:$CLASSPATH

Note: SQLJ also has a `-classpath` option. If you use the SQLJ `-classpath` option, following the JPublisher `-sqlj` option, then that setting is used for the classpath for translation and compilation, and any JPublisher `-classpath` option setting is ignored. It is more straightforward to use only the JPublisher `-classpath` option.

#### 6.1.14.2 Jav a Compiler

Use the `-compiler-executable` option if you want Java code generated by JPublisher to be compiled by anything other than the compiler that JPublisher would use by default on your system. Specify the path to an alternative compiler executable file. The syntax for this option is:

    -compiler-executable=path_to_compiler_executable

#### 6.1.14.3 Jav a Version

Use the `-vm` option if you want to use a JVM other than the JVM that JPublisher would use by default on your system. Specify the path to an alternative Java executable file. The syntax for this option is:

    -vm=path_to_JVM_executable

As an example, assume that JDK 1.4 is installed on a UNIX system at the location `JDK14`, relative to the current directory. Run JPublisher with the following command to use the JDK 1.4 JVM and compiler when publishing Web services client proxy classes:

    % jpub -vm=JDK14/bin/java -compiler-executable=JDK14/bin/javac
           -proxywsdl=hello.wsdl

### 6.1.15 SQLJ Migration Options

In Oracle Database 10g release 2 (10.2), JPublisher provides the following command-line options to support migrating SQLJ to JDBC applications:

- `-migrate`

  This option enables you to turn on SQLJ migration. The syntax for setting this option is as follows:

      -migrate[=true|false]

  The `-migrate` and `-migrate=true` settings are equivalent. Both these settings indicate that JPublisher should migrate SQLJ programs specified on the command line to JDBC programs. The `-migrate=false` turns off the migration mode, and SQLJ programs are translated and compiled into a Java program that possibly depends on the SQLJ run time. By default, if this option is not specified, then JPublisher behaves like `-migrate=false`.

- `-migconn`

  This option enables you to specify the default JDBC connection used by the migrated code. The default JDBC connection replaces the default `DefaultContext` instance in the SQLJ run time. The syntax for setting this option is as follows:

      -migconn=getter:getter,setter:setter
      -migconn=name[[:datasource|modifier][,modifier]*]

  In the first syntax, the `getter` and `setter` settings specify the getter and setter methods for the default connection. For example:

      -migconn=getter:Test.getDefConn,setter:Test.setDefConn

  In the second syntax, the `name` setting specifies the default JDBC connection. The optional `datasource` setting provides a JNDI data source location for initializing the default JDBC connection. The `modifier` settings add the modifiers for the default connection variable. You can specify more than one modifier by using multiple `modifier` settings. Examples of the usage of the second syntax are as follows:

      -migconn=_defaultConn:public,static
      -migconn=Test._defaultConn
      -migconn=Test._defaultConn:jdbc/MyDataSource
      -migconn=_defaultConn:public,static,final

- `-migrsi`

  This option enables you to specify an interface for all `ResultSet` iterator classes. The syntax for setting this option is as follows:

      -migrsi=java_interface_name

  For example:

      -migrsi=ResultSetInterface

- `-migsync`

  This option enables you to mark static variables as `synchronized`. The syntax for setting this option is as follows:

      -migsync[=true|false]

  The `-migsync` and `-migsync=true` settings mark static variables generated for migration purpose as synchronized. If you do not want the variables to be marked as synchronized, then set `-migsync=false`. By default, JPublisher behaves like `-migsync=true`.

- `-migdriver`

  This option enables you to specify the JDBC driver registered by the migrated code. The syntax for setting this option is as follows:

      -migdriver=class_name|no

  For example:

      -migdriver=oracle.jdbc.driver.OracleDriver

  By default, JPublisher behaves like `-migdriver=oracle.jdbc.driver.OracleDriver`. If you do not want the driver registration code to be generated during migration, then set this option as follows:

      -migdriver=no

- `-migcodegen`

  This option enables you to specify whether the migrated code depends on an Oracle JDBC driver or a generic JDBC driver. The syntax for setting this option is as follows:

      -migcodegen=oracle|jdbc

  The default behavior is `-migcodegen=oracle`, indicating that Oracle-specific JDBC APIs are used in the migrated code.

- `-migserver`

  This option enables you to specify whether to migrate the program to be used on the server. The syntax for setting this option is as follows:

      -migserver

See Also: `http://www.oracle.com/technology/tech/java/sqlj_jdbc/pdf/oracle_sqlj_roadmap.pdf`

## 6.2 JPublisher Input Files

The following sections describe the structure and contents of JPublisher input files:

- Properties File Structure and Syntax

- INPUT File Structure and Syntax

- INPUT File Precautions

### 6.2.1 Properties File Structure and Syntax

A properties file is an optional text file in which you can specify frequently used options. Specify the name of the properties file on the JPublisher command line with the `-props` option.

Note: `-props` is the only option that you cannot specify in a properties file.

On each line in a properties file, enter only one option with its associated value. Enter each option setting with the following prefix, including the period:

    jpub.

The `jpub.` prefix is case-sensitive. White space is permitted only directly in front of `jpub.`. Any other white space within the option line is significant.

Alternatively, JPublisher permits you to specify options with a double-dash (`--`), which is the syntax for SQL comments, as part of the prefix:

    -- jpub.

A line that does not start with either of the prefixes shown is simply ignored by JPublisher.

In addition, you can use line continuation to spread a JPublisher option over several lines in the properties file. A line to be continued must have a backslash character (`\`) as the last character, immediately after the text of the line. Any leading space or double dash (`--`) on the line that follows the backslash is ignored. Consider the following sample entries:

    /* The next three lines represent a JPublisher option
       jpub.sql=SQL_TYPE:JPubJavaType:MyJavaType,\
                OTHER_SQL_TYPE:OtherJPubType:MyOtherJavaType,\
                LAST_SQL_TYPE:My:LastType
    */
    -- The next two lines represent another JPublisher option
    -- jpub.addtypemap=PLSQL_TYPE:JavaType:SQL TYPE\
    --                :SQL_TO_PLSQL_FUNCTION:PLSQL_TO_SQL_FUNCTION

Using this functionality, you can embed JPublisher options in SQL scripts, which may be useful when setting up PL/SQL-to-SQL type mappings.

JPublisher reads the options in the properties file in order, as if its contents were inserted on the command line at the point where the `-props` option is located. If you specify an option more than once, then the last value encountered by JPublisher overrides previous values, except for the following options, which are cumulative:

- `jpub.sql` (or the deprecated `jpub.types`)

- `jpub.java`

- `jpub.style`

- `jpub.addtypemap`

- `jpub.adddefaulttypemap`

For example, consider the following command:

    % jpub -user=scott/tiger -sql=employee -mapping=oracle -case=lower -package=corp -dir=demo

Now consider the following:

    % jpub -props=my_properties

This command is equivalent to the first example if you assume that `my_properties` has a definition such as the following:

    -- jpub.user=scott/tiger
    // jpub.user=cannot_use/java_line_comments
    jpub.sql=employee
    /*
    jpub.mapping=oracle
    */
    Jpub.notreally=a jpub option
       jpub.case=lower
    jpub.package=corp
        jpub.dir=demo

You must include the `jpub.` prefix at the beginning of each option name. If you enter anything other than white space or double dash (`--`) before the option name, then JPublisher ignores the entire line.

The preceding example illustrates that white space before `jpub.` is okay. It also shows that the `jpub.` prefix must be all lowercase, otherwise it is ignored. Therefore the following line from the preceding example will be ignored:

    Jpub.notreally=a jpub option

### 6.2.2 INPUT File Structure and Syntax

Specify the name of the `INPUT` file on the JPublisher command line with the `-input` option. This file identifies SQL user-defined types and PL/SQL packages that JPublisher should translate. It also controls the naming of the generated classes and packages. Although you can use the `-sql` command-line option to specify user-defined types and packages, an `INPUT` file allows you a finer degree of control over how JPublisher translates them.

If you do not specify types or packages to translate in an `INPUT` file or on the command line, then JPublisher translates all user-defined types and PL/SQL packages in the schema to which it connects.

#### 6.2.2.1 Understan ding the Translation Statement

The translation statement in the `INPUT` file identifies the names of the user-defined types and PL/SQL packages that you want JPublisher to translate. Optionally, the translation statement can also specify a Java name for the type or package, a Java name for attribute identifiers, and whether there are any extended classes.

One or more translation statements can appear in the `INPUT` file. The structure of a translation statement is as follows:

    ( SQL name
    | SQL [schema_name.]toplevel  [(name_list)]
    | TYPE type_name)
    [GENERATE java_name_1]
    [AS java_name_2]
    [TRANSLATE
         database_member_name AS simple_java_name
     { , database_member_name AS simple_java_name}*
    ]

The following sections describe the components of the translation statement.

SQL name | TYPE type_name Enter `SQL` `name` to identify a SQL type or a PL/SQL package that you want JPublisher to translate. JPublisher examines the `name`, determines whether it is for a user-defined type or a PL/SQL package, and processes it appropriately. If you use the reserved word `toplevel` in place of `name`, JPublisher translates the top-level subprograms in the schema to which JPublisher is connected.

Instead of `SQL`, it is permissible to enter `TYPE` `type_name` if you are specifying only object types. However, the `TYPE` syntax is deprecated.

You can enter `name` as `schema_name`.`name` to specify the schema to which the SQL type or package belongs. If you enter `schema_name`.`toplevel`, JPublisher translates the top-level subprograms in schema `schema_name`. In conjunction with `TOPLEVEL`, you can also supply `name_list`, which is a comma-delimited list of names to be published, enclosed in parentheses. JPublisher considers only top-level functions and procedures that match this list. If you do not specify this list, JPublisher generates code for all top-level subprograms.

Note: If a user-defined type is defined in a case-sensitive way in SQL, then you must specify the name in quotes. For example:
    SQL "CaseSenstiveType" AS CaseSensitiveType
Alternatively, you can also specify a schema name that is not case-sensitive:
    SQL SCOTT."CaseSensitiveType" AS CaseSensitiveType
You can also specify a case-sensitive schema name:
    SQL "Scott"."CaseSensitiveType" AS CaseSensitiveType
The `AS` clause is optional. Avoid situations where a period (".") is part of the schema name or the type name itself.

GENE RATE java_name_1 AS java_name_2 The `AS` clause specifies the name of the Java class that represents the SQL user-defined type or PL/SQL package being translated.

When you use the `AS` clause without a `GENERATE` clause, JPublisher generates the class in the `AS` clause and maps it to the SQL type or PL/SQL package.

When you use both the `GENERATE` clause and the `AS` clause for a SQL user-defined type, the `GENERATE` clause specifies the name of the Java class that JPublisher generates, which is referred to as the base class. The `AS` clause specifies the name of a Java class that extends the generated base class, which is referred to as the user subclass. JPublisher produces an initial version of the user subclass, and you will typically add code for your desired functionality. JPublisher maps the SQL type to the user subclass, and not to the base class. If you later run the same JPublisher command to republish the SQL type, then the generated class is overwritten, but the user subclass is not.

The `java_name_1` and `java_name_2` can be any legal Java names and can include package identifiers. The case of the Java names overrides the `-case` option.

TRANSLATE database_member_name AS simple_java_name This clause optionally specifies a different name for an attribute or method. The `database_member_name` is the name of an attribute of a SQL object type or the name of a method of an object type or PL/SQL package. The attribute or method is to be translated to `simple_java_name`, which can be any legal Java name. The case of the Java name overrides the `-case` option. This name cannot have a package name.

If you do not use `TRANSLATE...AS` to rename an attribute or method, or if JPublisher translates an object type not listed in the `INPUT` file, then JPublisher uses the database name of the attribute or method as the Java name. If applicable, the Java name is modified according to the setting of the `-case` option. Reasons why you may want to rename an attribute or method include:

- The name contains characters other than letters, digits, and underscores.

- The name conflicts with a Java keyword.

- The type name conflicts with another name in the same scope. This can happen, for example, if the program uses two types with the same name from different schemas.

Remember that your attribute names will appear embedded within `get` `XXX``()` and `set` `XXX``()` method names, so you may want to capitalize the first letter of your attribute names. For example, if you enter:

    TRANSLATE FIRSTNAME AS FirstName

JPublisher generates a `getFirstName()` method and a `setFirstName()` method. In contrast, if you enter:

    TRANSLATE FIRSTNAME AS firstName

JPublisher generates a `getfirstName()` method and a `setfirstName()` method.

Note: The Java keyword `null` has special meaning when used as the target Java name for an attribute or method, such as in the following example:
    TRANSLATE FIRSTNAME AS null
When you map a SQL method to `null`, JPublisher does not generate a corresponding Java method in the mapped Java class. When you map a SQL object attribute to `null`, JPublisher does not generate the getter and setter methods for the attribute in the mapped Java class.

Package Na ming Rules in the INPUT File You can specify a package name by using a fully qualified class name in the `INPUT` file. If you use a simple, unqualified class name in the `INPUT` file, then the fully qualified class name includes the package name from the `-package` option. This is demonstrated in the following examples:

- Assume the following in the `INPUT` file:

      SQL A AS B

  And assume the setting `-package=a.b`. In this case, `a.b` is the package and `a.b.B` is the fully qualified class name.

- Assume that you enter the following in the `INPUT` file and there is no `-package` setting:

      SQL A AS b.C

  The package is `b`, and `b.C` is the fully qualified class name.

See Also: "Name for Generated Java Package"

Note: If there are conflicting package settings between a `-package` option setting and a package setting in the `INPUT` file, then the precedence depends on the order in which the `-input` and `-package` options appear on the command line. The `-package` setting takes precedence if that option is after the `-input` option, else the `INPUT` file setting takes precedence.

Translating Additional Types It may be necessary for JPublisher to translate additional types that are not listed in the `INPUT` file. This is because JPublisher analyzes the types in the `INPUT` file for dependencies before performing the translation and translates any additional required types.

Consider the example in "Sample JPublisher Translation". Assume that the object type definition for `EMPLOYEE` includes an attribute called `ADDRESS`, and `ADDRESS` is an object with the following definition:

    CREATE OR REPLACE TYPE address AS OBJECT
    (
        street     VARCHAR2(50),
        city       VARCHAR2(50),
        state      VARCHAR2(30),
        zip        NUMBER
    );

In this case, JPublisher would first translate `ADDRESS,` because that would be necessary to define the `EMPLOYEE` type. In addition, `ADDRESS` and its attributes would all be translated in the same case, because they are not specifically mentioned in the `INPUT` file. A class file would be generated for `Address.java`, which would be included in the package specified on the command line.

JPublisher does not translate PL/SQL packages you do not request, because user-defined types or other PL/SQL packages cannot have dependencies on PL/SQL packages.

#### 6.2.2.2 Sample Translation Statement

To better illustrate the function of the `INPUT` file, consider an updated version of the example in "Sample JPublisher Translation".

Consider the following command:

    % jpub -user=scott/tiger -input=demoin -numbertypes=oracle -usertypes=oracle -dir=demo -d=demo -package=corp -case=same

And assume that the `INPUT` file `demoin` contains the following:

    SQL employee AS Employee
    TRANSLATE NAME AS Name HIRE_DATE AS HireDate

The `-case=same` option specifies that generated Java identifiers maintain the same case as in the database, except where you specify otherwise. Any identifier in a `CREATE TYPE` or `CREATE PACKAGE` declaration is stored in uppercase in the database unless it is quoted. In this example, the `-case` option does not apply to the `EMPLOYEE` type, because `EMPLOYEE` is specified to be translated as the Java class `Employee`.

For attributes, attribute identifiers not specifically mentioned in the `INPUT` file remain in uppercase, but JPublisher translates `NAME` and `HIRE_DATE` as `Name` and `HireDate`, as specified.

The translated `EMPLOYEE` type is written to the following files, relative to the current directory, for UNIX in this example, reflecting the `-package`, `-dir`, and `-d` settings:

    demo/corp/Employee.java
    demo/corp/Employee.class

### 6.2.3 INPUT File Precautions

This section describes possible `INPUT` file error conditions that JPublisher will currently not report. There is also a section for reserved terms.

#### 6.2.3.1 Requesting the Same Java Class Name for Different Object Types

If you request the same Java class name for two different object types, the second class overwrites the first without warning. Consider that the `INPUT` file contains:

    type PERSON1 as Person
    type PERSON2 as Person

JPublisher creates the `Person.java` file for `PERSON1` and then overwrites it for the `PERSON2` type.

#### 6.2.3.2 Requesting the Same Attribute Name for Different Object Attributes

If you request the same attribute name for two different object attributes, JPublisher generates `get` `XXX``()` and `set` `XXX``()` methods for both attributes without issuing a warning message. The question of whether the generated class is valid in Java depends on whether the two `get` `XXX``()` methods with the same name and the two `set` `XXX``()` methods with the same name have different argument types so that they may be unambiguously overloaded.

#### 6.2.3.3 Specifying Nonexistent Attributes

If you specify a nonexistent object attribute in the `TRANSLATE` clause, then JPublisher ignores it without issuing a warning message.

Consider the following example from an `INPUT` file:

    type PERSON translate X as attr1

A situation in which `X` is not an attribute of `PERSON` does not cause JPublisher to issue a warning message.

#### 6.2.3.4 JPublisher Reserved Terms

Do not use any of the following reserved terms as SQL or Java identifiers in the `INPUT` file.

    AS
    GENERATE
    IMPLEMENTS
    SQLSTATEMENTS_TYPE
    SQLSTATEMENTS_METHOD
    SQL
    TRANSLATE
    TOPLEVEL
    TYPE
    VERSION